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

Common Challenges When Transforming FHIR to OMOP

Page standards status: Trial-use

Highlight text changes?

Aligning FHIR resources with the OMOP Common Data Model presents challenges due to differences in their data structures, scope, and intended purposes. The complexity increases because most observational data sources aren't natively generated as FHIR, meaning many FHIR resources have already undergone transformation before any OMOP conversion begins. This creates a need for pragmatic alignment approaches that preserve essential source data context for transactional use cases while achieving OMOP conformance for analytics.

The tension between the the two standards stems from FHIR's design for real-time clinical data exchange and workflow support versus OMOP's structure for research analytics and retrospective analysis with standardized terminology. This divergence means that poorly considered mappings can misrepresent data, particularly given OMOP's requirements for concept standardization and validated data quality procedures that must be carefully addressed when transforming patient records from FHIR format.

A Transformation Engine SHALL produce output conforming to the OMOP Common Data Model version 5.4, and a Target OMOP Instance SHALL conform to the OMOP CDM v5.4 schema.^§f2o-001 An Implementer SHALL declare the FHIR version or versions of the source data that the transformation is configured to consume.^§f2o-002

Status and Intent Elements in FHIR Resources

Many FHIR resources carry elements that describe where a clinical activity sits in an administrative or care delivery workflow rather than describing the clinical fact itself. A MedicationRequest could be active, on-hold, or cancelled. A Procedure could be preparation, in-progress, completed, or not-done. A ServiceRequest carries both a status and an intent, the latter distinguishing a proposal from a plan from an order.

The OMOP CDM makes a different assumption. Its clinical event tables represent things that happened: a drug_exposure record asserts that a patient was exposed to a drug, and a procedure_occurrence record asserts that a procedure was performed. OMOP has no general mechanism for representing an event that was contemplated but did not occur, and analytic tooling built on OMOP assumes throughout that records describe realized events.

This mismatch is consequential. A FHIR export that includes cancelled orders, proposed procedures, and draft prescriptions describes a superset of what happened to the patient. Transformed without filtering, those records inflate apparent exposure and event rates, and the resulting analyses overstate what the patient actually received. The error is systematic rather than random, and it is invisible in the target: nothing in a drug_exposure record indicates that its source was a cancelled order.

Distinguishing Status from Intent

The two element types answer different questions and require separate evaluation. Status describes the state of the record or activity in its workflow: whether it is in progress, completed, abandoned, or entered in error. Intent, present on request-pattern resources such as MedicationRequest, ServiceRequest, and CarePlan, describes the degree of commitment the record represents: whether it is a proposal, a plan, an order, or an instance of an order.

The interaction of the two is decisive for the request resources, and it is not always intuitive. For MedicationRequest, the reference test suite admits a drug_exposure row only where the intent is instance-order, and it does so regardless of status; every other intent value produces no row. The reason is semantic rather than arbitrary: within the IPA pattern, an instance-order MedicationRequest is the equivalent of a medication administration record, the point at which a prescription becomes an event that happened to the patient. A proposal, a plan, or a plain order records an intention, not an administration. Evaluating status alone would admit records that intent alone would correctly reject, so both elements must be evaluated where both are present.

Resource-Specific Evaluation

The tables below summarize the elements requiring evaluation for the resources most commonly encountered in FHIR-to-OMOP transformation, and indicate which values describe realized events. The dispositions shown here are aligned with the FHIR-to-OMOP unit test specifications, which are the governing reference: where an implementation's filter rule disagrees with the test suite, the test suite prevails. Values not enumerated for a given resource ought to be treated as not realized until the test suite assigns them.

MedicationRequest to drug_exposure

Element	Values describing a realized event	Values producing no row
intent	instance-order	proposal, plan, order, original-order, reflex-order, filler-order, option
status	active, completed (only in combination with intent = instance-order)	draft, on-hold, cancelled, stopped, entered-in-error, unknown

For MedicationRequest, intent is the primary filter: only instance-order produces a row, and it does so irrespective of status. Status is then evaluated within the admitted intent. Note that a MedicationRequest describes a prescription rather than an administration; the limitations of inferring exposure from prescription data are discussed in ETL Documentation on the Strategies and Best Practices page.

MedicationStatement to drug_exposure

Element	Values describing a realized event	Values producing no row
status	active, completed	entered-in-error, intended, stopped, on-hold, unknown, not-taken

MedicationStatement follows the more direct pattern: status alone governs, and only active and completed are realized. statusReason handling is unresolved in the test suite and is not relied on here.

Procedure to procedure_occurrence

Element	Values describing a realized event	Values producing no row
status	completed	preparation, in-progress, not-done, on-hold, stopped, unknown, entered-in-error

Two values warrant comment. not-done asserts positively that a procedure did not occur, and such records must never become procedure occurrences; where a Procedure carries not-done together with a statusReason, the fact of non-performance could itself be clinically meaningful and can be captured in the observation domain if the OMOP instance requires it. in-progress is filtered by the test suite: a procedure in progress at export time has not completed, and the suite treats it as not realized rather than as an implementer judgment call.

Observation to measurement or observation

Element	Values describing a realized event	Values producing no row
status	final, amended, corrected	registered, preliminary, cancelled, entered-in-error, unknown

preliminary is filtered by the test suite. A separate rule applies to dataAbsentReason: an Observation carrying a data absent reason produces no clinical event row, since OMOP rejects the "flavors of null" pattern. Data absent reason handling is treated in its own right under Data Absent Reasons Elements below.

Condition to condition_occurrence or observation

Condition does not reduce to a realized-or-excluded status filter, because verificationStatus routes records across domains rather than admitting or rejecting them wholesale.

verificationStatus	Disposition
confirmed	condition_occurrence row
unconfirmed	no row
entered-in-error	no row
provisional	observation row, qualifier_concept_id = preliminary diagnosis
differential	observation row, qualifier_concept_id = differential
refuted	observation row, qualifier_concept_id = refuted

The provisional, differential, and refuted dispositions place the record in the observation domain as a qualified concept rather than discarding it, which preserves the clinical signal that a diagnosis was considered and characterizes how. clinicalStatus values such as recurrence, relapse, inactive, remission, and resolved likewise route to the observation domain as qualifiers; the test suite carries these as a stretch-tier assertion, so implementations ought to treat the specific qualifier mappings as provisional.

Encounter to visit_occurrence

Element	Values describing a realized event	Values producing no row
status	finished (also in-progress, arrived, and triaged, subject to end-date derivation below)	planned, cancelled, entered-in-error, unknown

Encounter is the one resource where an in-flight status is admitted rather than filtered. An encounter that is arrived, triaged, or in-progress at export time has begun, so it produces a visit_occurrence row, but its end must be derived rather than read: for inpatient class the visit_end is set to the extraction date and the visit_type is recorded as "Still Patient," and for outpatient class the end defaults to the start. This is a date-derivation obligation rather than a filtering one, and it is exercised by the temporal tests rather than the status tests.

Immunization to drug_exposure

Element	Values describing a realized event	Values producing no row
status	completed	not-done, entered-in-error

not-done asserts the immunization was not given and produces no row.

Entered-in-Error Across All Resources

Entered-in-error deserves separate mention because it behaves uniformly across every resource type above. It does not mean that an event did not occur; it means the record itself is invalid and ought to be treated as though it had never been created. Such records are excluded from transformation regardless of any other element value, and ought not be represented in the target in any form.

Modifier Elements and Extensions

Status and intent are not the only elements that can invert or qualify the meaning of a resource. FHIR modifier elements, including modifierExtension and elements such as Condition.verificationStatus, can change a record's meaning in ways that a transformation ignoring them would misrepresent. A resource carrying an unrecognized modifier extension cannot be safely transformed on the assumption that the extension is decorative. The same discipline extends to terminology operations that fail: when a translation cannot be resolved, an engine that silently emits a concept_id of zero without recording the failure has discarded a modifier on the data's meaning just as surely as one that ignores a modifierExtension. This screening is treated in full in Understanding FHIR Modifier Extensions.

Consistency Across Loads

An OMOP instance built from FHIR is rarely populated once. Data arrive incrementally over the operational life of the instance, and filter rules applied inconsistently across loads produce a target whose composition varies by ingestion date. A cohort assembled across such a target will include cancelled orders from one period and exclude them from another, and the resulting bias is undetectable from within the data.

Filter rules ought to therefore be treated as a fixed property of the transformation rather than a runtime decision, versioned alongside the transformation logic, and changed only deliberately. Where filter rules do change, the change and its effective date belong in the ETL documentation, since analysts working across the boundary need to know the target's composition is not uniform.

Reporting Exclusions

Filtering is silent by construction: an excluded resource leaves no trace in the target. A transformation that filters without reporting therefore gives its users no way to distinguish a patient with no medication exposure from a patient whose every order was cancelled, and no way to detect a filter rule misfiring across a whole load.

A per-run exclusion report addresses this. At minimum it records counts by resource type and by exclusion reason, so that a load excluding an unusual proportion of records is visible before the target is used. Such a report also serves the ETL documentation obligation, since it evidences that the documented filter rules were the rules actually applied.

This report is strongly advised rather than required, and the reason for the distinction is worth stating plainly. A run-level exclusion report is a build obligation: it asks an engine to produce an artifact many transformation pipelines do not currently emit, and an engine that filters correctly but does not report its exclusions is doing the substantive work right while lacking only the audit trail. Making the report mandatory would place that otherwise-correct engine out of conformance on the strength of a missing artifact rather than a mapping defect, and an Implementation Guide that manufactures non-conformance from otherwise-sound transformations raises the cost of adoption without improving the data those transformations produce. The stronger case is the one made on the merits: because filtering is invisible in the target, the exclusion report is the only place a silent filtering error becomes detectable before analysis, and the only artifact that lets a downstream analyst tell a genuinely empty history from a fully filtered one. An implementer who understands that hazard will build the report because it protects their own analyses, which is a more durable reason to build it than a conformance clause. The guidance below is therefore not mandatory, and the narrative above is written to earn it rather than to compel it.

Guidance

A Transformation Engine SHALL evaluate status and intent elements and SHALL NOT transform resources describing events that were not realized, including those cancelled, proposed, planned, not done, stopped, or entered in error, into OMOP clinical event tables.^§f2o-060

A Transformation Engine and Implementer SHALL apply consistent filter rules across all incremental loads into a given OMOP instance, and SHALL record any change to those rules, with its effective date, in the ETL documentation.^§f2o-061

A Transformation Engine SHOULD emit a run-level report of resources excluded by filter, recording counts by resource type and exclusion reason.^§f2o-062

A Transformation Engine SHALL evaluate FHIR modifier elements and SHALL NOT silently transform a resource whose modifier elements alter its clinical interpretation, nor silently emit a concept_id of zero when a terminology lookup fails without recording the failure.^§f2o-063

Data Completeness, Missingness & Integrity

Handling incomplete or partial data presents an additional challenge in transforming FHIR resources to OMOP. FHIR records are often incomplete for several reasons: the source electronic health record (EHR) itself could contain partial entries, or the FHIR resources could only include a subset of available data tailored to the specific purpose of the resource. In contrast, the OMOP data model assumes that critical fields such as dates, person references, and coded concepts are consistently populated to support standardized analysis.

When transforming FHIR to OMOP, these gaps require careful consideration to avoid introducing ambiguity or bias. For example, a FHIR MedicationStatement could be missing start or end dates, which makes it unclear whether the medication ought to be interpreted as active, historical, or intended. Similarly, a procedure or encounter record could lack information about the performer or the location, undermining the ability to analyze provider performance, regional variation, or care delivery patterns.

One approach to address these challenges is to consider fallback strategies that preserve as much context as possible. Implementers can use the OMOP observation domain or the note table to retain essential but incomplete data when no direct mapping is feasible. In cases where fields such as dates are missing, records can be flagged as incomplete by selecting appropriate ‘type’ concept IDs to indicate that the data is estimated or partial. This practice ensures that analysts reviewing the transformed data are aware of the uncertainty inherent in these records.

It is equally important for implementers to reflect on the implications of partial data for downstream analyses. Records with incomplete information could introduce misinterpretation or bias if not carefully accounted for in study design and statistical modeling. Therefore, teams ought to exercise caution when drawing inferences from datasets containing records transformed from incomplete FHIR sources.

Contextual Gaps in Data Mapping

A challenge faced in transforming FHIR to OMOP is that FHIR resources often contain contextual elements such as reasonCode, performer, location, or supportingInfo that help clarify the conditions or context surrounding a clinical event. OMOP tables do not have a direct way to represent these contexts fully in the same way that FHIR has structured this information. While core information could be mapped to OMOP fields in most instances, key context might be lost if certain contextual elements cannot be directly represented, impacting downstream analytics. For example, reasonCode in FHIR can specify the purpose of a procedure, such as preventive care vs. diagnostic intervention. This nuance can be critical to outcomes analyses but could not be directly captured in OMOP. Also of issue is that lacking context, such as missing details on “why” a procedure was performed or medication prescribed could lead to misinterpretations in analysis, particularly for longitudinal studies tracking disease progression or treatment efficacy.

One workaround could be to capture the context in a generic OMOP extension, such as "note," but this would have limitations. Another workaround would be to create specific OMOP extensions for the relevant FHIR elements. This would still have limitations as it produces non-standard OMOP implementations. Further, any extension suggested as universally applicable for FHIR source data would suggest implementation of OMOP CDM non-conformant as a routine. Rather, for the scope of this implementation guide, we want to call attention to the limitation and suggest review of the source data for potential proxies in the choices made for target Standard concepts, special attention to selection of record ‘type’ concepts that confer metadata about the source records or ensuring linkage in the transformed data to specific visit_occurrence records to approximate some context potentially lost. As suggested with identifiers, if the contextual information potentially lost in transformation cannot be accommodated and is critical to the research intended, then accommodation with concept or table extensions could be considered.

HL7 Flavors of Null and OMOP

When implementing an HL7 FHIR to OMOP transformation using a FHIR Implementation Guide (IG), handling null values or flavors of null is a critical concern. In HL7 FHIR, data absence can be explicitly communicated using extensions like data-absent-reason, which distinguishes between unknown, asked-but-unknown, or not-applicable values. OMOP CDM, however, represents nulls more implicitly: fields could be left empty, or encoded using specific concepts like 0 (for “No matching concept”) or NULL in SQL. Mapping between these two paradigms requires careful alignment to avoid misinterpretation of data. For instance, a FHIR Observation with a data-absent-reason = unknown must be mapped meaningfully to the OMOP measurement table, potentially setting the value_as_number and value_as_concept_id to NULL, while assigning an appropriate observation_concept_id to indicate that the test was performed but the result was unavailable.

Comparison Table: FHIR vs OMOP Flavors of Null

Aspect	HL7 FHIR	OMOP CDM
Representation of null	data-absent-reason extension	NULL in SQL or concept ID = 0
Granularity of nulls	Fine-grained (unknown, not-applicable, masked, etc.)	Implicit; often lacks detailed flavor semantics
Standard terminology	Uses codes like unknown, not-asked, etc.	No standard codes; often relies on documentation or conventions
Handling missing values	Structured via extensions or empty elements with context	Fields left NULL or set to 0 (no matching concept)
ETL challenge	Requires preserving semantic meaning during mapping	Requires selecting appropriate mapping logic per use case

In short, FHIR provides a more expressive mechanism to convey the reason for missing data, while OMOP assumes nulls are more operational or structural. Mapping between them in a FHIR-to-OMOP ETL process requires deliberate rules to preserve clinical meaning without overfitting to the destination model.

OMOP provides *_source_value fields that can be leveraged to carry forward original FHIR null semantics (e.g., “refused” or “masked”) when they do not map cleanly to a standard concept. For instance, a FHIR Observation with data-absent-reason = not-permitted could result in a NULL value_as_number and value_as_concept_id, but the string "not-permitted" could be preserved in the value_source_value field. This approach ensures that valuable context about the data's absence is not lost in the transformation, preserving semantic integrity across models.

Data Absent Reasons Elements

The Data Absent Reason element in FHIR allows implementers to record why information is missing or incomplete in observations, medication statements, and immunizations. When using FHIR resources that document reasons for absent data, it is important to assess carefully which of these reasons ought to be included in OMOP. This consideration applies to common scenarios such as missing lab results, medications that were not administered, or declined immunizations.

Because Data Absent Reasons cover a spectrum ranging from clinically meaningful refusals to routine administrative gaps, a selective approach is recommended. Implementers are encouraged to map only those reasons with clear clinical or research value for the intended use case, which could include or exclude information such as patient refusals, or adverse reactions, while excluding operational or ambiguous reasons like “unknown” or “unsupported.”

In FHIR, Data Absent Reasons use codes such as “unknown,” “not asked,” “asked but unknown,” and “not applicable,” reflecting nuances in why data were not captured. For example, a lab result ordered but not performed could be marked “patient declined,” while a medication not taken might be recorded as due to side effects.

Determining how to represent FHIR’s Data Absent Reasons in OMOP requires both technical and clinical considerations. Because FHIR reasons encompass both clinical and operational rationale, it is recommended to retain only clinically significant reasons that can be mapped to standard vocabularies such as SNOMED or OMOP concepts. This approach helps implementers balance the completeness of data capture with the need for clarity and analytic utility, preserving the clinical relevance and analytic focus of the OMOP model to support the intended research use cases.

Temporal Precision in OMOP and FHIR

The way a data model records time shapes ETL design, permissible analyses, and the scientific questions a dataset can answer. FHIR provides flexible temporal datatypes with precision ranging from year-only to millisecond timestamps, designed to support real-time clinical workflows and system interoperability [1]. By contrast, the OMOP Common Data Model requires date-level fields (YYYY-MM-DD) while providing optional datetime fields that can preserve sub-day precision when populated [2]. This design reflects a deliberate trade-off: it simplifies data sharing, removes variability introduced by differing timestamp conventions, and aligns with OMOP's chief aim: large-scale, retrospective, observational research where day-level granularity is generally sufficient for most analytical use cases.

FHIR Temporal Datatypes

FHIR defines multiple temporal primitive types with distinct precision and constraint requirements [1]:

FHIR Type	Precision	Timezone Requirement	Example
instant	Milliseconds (required to second minimum)	Mandatory	2015-02-07T13:28:17.239+02:00
dateTime	Variable (year to millisecond)	Mandatory when time specified	2024, 2024-03, 2024-03-15T14:30:00Z
date	Day, month, or year	Prohibited	2024-03-15, 2024-03, 2024
time	Time of day only	Prohibited	14:30:00

This flexibility allows FHIR to represent clinical events at the precision appropriate to the source system. The instant type is explicitly designated for "precisely observed times" such as system logs, while dateTime accommodates human-reported times where precision could vary [1]. Critically, FHIR mandates timezone specification whenever time components are present in instant or dateTime values.

Core Implementation Pattern in OMOP

Because OMOP treats the calendar day as the atomic temporal unit for required fields, every _date column is stored as a SQL DATE. For example, condition_start_date captures when a diagnosis was first recorded, whereas visit_start_date and visit_end_date bracket an encounter. End-date fields could be NULL for chronic conditions, long-term drug exposures, or any scenario where the source system never records cessation. Avoiding imputed end dates prevents false precision but requires ETL architects to document any necessary imputations for downstream transparency.

Optional Datetime Fields in OMOP

OMOP CDM v5.4 provides optional *_datetime fields alongside required *_date fields in most clinical event tables [2,3]. These datetime fields can preserve sub-day temporal information when source data contains timestamps:

Field Type	Required	Data Type	Precision Capability
*_date fields	Yes	DATE	Day (YYYY-MM-DD)
*_datetime fields	No	DATETIME	Platform-dependent (typically seconds to microseconds)

The OMOP CDM specification states: "If a source does not specify datetime the convention is to set the time to midnight (00:00:0000)" [3]. This convention introduces ambiguity between events that actually occurred at midnight and events for which time was unknown.

The optional status of datetime fields reflects a deliberate community decision. OMOP CDM v6.0 proposed making datetime fields mandatory, but this version was not adopted. The official documentation explains: "The major difference in CDM v5.3 and CDM v6.0 involves switching the *_datetime fields to mandatory rather than optional. This switch radically changes the assumptions related to exposure and outcome timing. Rather than move forward with v6.0, CDM v5.4 was designed with additions to the model that have been requested by the community while retaining the date structure of medical events in v5.3" [4]. Organizations are advised to transform data to CDM v5.4 "until such time that the v6 series of the CDM is ready for mainstream use" [4].

Implementer Recommendation: When FHIR source data contains precise timestamps, ETL pipelines ought to populate the optional OMOP datetime fields to preserve this information. However, implementers ought to document which datetime values represent actual recorded times versus imputed midnight defaults, as this distinction affects analytical validity.

OMOP Domain Requirements

Some domains demand particular temporal fields. The following table summarises the expectations in core OMOP tables.

Domain-specific temporal fields in OMOP

Domain	Required Temporal Fields	Optional Datetime Fields	Notes
Condition	condition_start_date (required) / condition_end_date (optional)	condition_start_datetime / condition_end_datetime	Diagnosis date mandatory; end date often NULL for chronic illnesses.
Drug Exposure	drug_exposure_start_date (required) / drug_exposure_end_date (optional)	drug_exposure_start_datetime / drug_exposure_end_datetime	Records prescription fill and, where known, supply duration.
Procedure	procedure_date (required)	procedure_datetime	Exact date for surgical or diagnostic procedures.
Visit Occurrence	visit_start_date, visit_end_date (both required)	visit_start_datetime, visit_end_datetime	Defines the encounter window.
Measurement / Observation	measurement_date / observation_date (required)	measurement_datetime / observation_datetime	Sub-day precision preserved only if datetime fields populated.

Information That Cannot Be Fully Preserved

When transforming FHIR data to OMOP, certain temporal information cannot be fully represented even when optional datetime fields are populated:

Timezone Information

FHIR's instant datatype mandates timezone specification (e.g., +02:00 or Z for UTC) [1]. Standard ANSI SQL DATETIME types, which the OMOP CDM specifies generically [2], do not include timezone offset. The SQL standard specifies that timestamp without qualification is "equivalent to timestamp without time zone" [5]. Preserving timezone requires database-specific extensions such as DATETIMEOFFSET (SQL Server) or TIMESTAMP WITH TIME ZONE (PostgreSQL), which are not mandated by the OMOP CDM specification. For multi-site studies spanning time zones or analyses sensitive to absolute time (e.g., circadian rhythm research), this loss could be significant.

Normalizing Time Zones on Ingestion

Because the CDM does not carry a time zone, a *_datetime column populated from sources in different zones is ambiguous in a way that is invisible on inspection: two values an hour apart may represent the same instant or genuinely different ones, and nothing in the target distinguishes the cases. The hazard is not the loss of the offset, which the model cannot hold in any event, but the mixing of zones within one column.

The remedy is to convert on ingestion rather than on read. Where a source value carries an offset, it ought to be converted to a single zone applied consistently across the instance, conventionally UTC, before the *_datetime field is populated, and the chosen zone ought to be stated in the ETL documentation so analysts know what the column means. Where preservation of the original offset matters to the research, it belongs in an auxiliary store or a database-specific column outside the standard schema, as described above.

Precision Metadata

FHIR's variable-precision dateTime type distinguishes between values known only to the year (2024), year-month (2024-03), day (2024-03-15), or full timestamp (2024-03-15T14:30:00Z) [1]. OMOP provides no standard mechanism to capture this precision metadata. When a year-only FHIR date is transformed to OMOP, the ETL must impute a complete date (typically YYYY-01-01), but the original precision level is not preserved in a queryable field. The *_source_value columns can document the original representation, but this requires manual inspection rather than programmatic filtering.

Sub-second Precision Variability

The OMOP CDM documentation acknowledges platform-dependent datetime handling: "The CDM does not prescribe the date and datetime format. Standard queries against CDM could vary for local instantiations and date/datetime configurations" [2]. Database implementations vary in datetime precision: traditional SQL Server DATETIME rounds to 3.33 milliseconds, while DATETIME2 supports 100-nanosecond precision [6]. Without specification of minimum precision requirements, OMOP implementations could truncate FHIR's millisecond-precision timestamps.

Summary of Temporal Information Preservation

Information Type	FHIR Capability	OMOP Preservation	Notes
Date (day precision)	Full support	Required fields	Fully preserved
Time of day	Full support	Optional datetime fields	Preserved if datetime fields populated
Timezone offset	Mandatory for instant	No standard field	Typically lost
Sub-second precision	Milliseconds	Platform-dependent	Variable
Precision metadata	Implicit in format	No standard field	Lost; requires *_source_value documentation

Limitations and Intra-Day Challenges

When optional datetime fields are not populated, which remains common practice given their optional status and the historical prevalence of date-only source data [7], sub-day precision is lost entirely. Even when datetime fields are populated, the absence of timezone creates challenges. Intensive-care interventions, rapid laboratory results, and overlapping medication administrations can occur within minutes; without consistent datetime population and timezone handling, such events could collapse onto the same calendar day or be ambiguously ordered across time zones. Analysts must therefore supplement with auxiliary timestamp stores or infer ordering through other means. Likewise, temporal ties, multiple events stamped with the same date, demand caution in sequence analyses lest spurious causal relationships be inferred.

Handling Partial or Approximate Dates When Mapping from FHIR

Mapping FHIR resources into OMOP often surfaces partial or approximate temporal metadata. Historical records, patient-reported information, or legacy migrations could capture only a year (2024) or a year-month (2024-05). FHIR explicitly supports these partial representations through the date and dateTime datatypes' variable precision [1]. If an exact date is indispensable for OMOP, implementers can adopt controlled imputations: for example, defaulting year-only data to YYYY-01-01 or year-month data to the first of that month. Every rule must be logged in ETL metadata, preserved in *_source_value columns, and communicated to analysts so sensitivity analyses can account for uncertainty.

Implementers ought to consider creating a supplementary precision indicator when partial dates are common in source data. While not part of the standard OMOP CDM, a local extension table documenting the original temporal precision for each record can enable analysts to filter or weight observations based on date certainty.

Analytical Implications

Despite its limitations, the OMOP temporal model underpins a wide array of research tasks. Cohort definitions hinge on date fields for inclusion windows; comparative-effectiveness studies rely on day-level ordering of diagnoses, procedures, and prescriptions; and longitudinal trend analyses benefit from the removal of artefactual timestamp variability. Studies demanding minute-by-minute sequencing, such as antimicrobial stewardship audits in intensive-care units, could require either OMOP extensions or alternative data models altogether.

Recommendations for FHIR-to-OMOP Temporal Mapping

Based on the considerations above, implementers should:

1. Populate optional datetime fields when FHIR source data contains time components, rather than discarding this information by mapping only to required date fields.

2. Document datetime provenance by distinguishing between datetime values derived from actual FHIR timestamps versus those defaulted to midnight due to missing time components. Consider using type concept IDs or supplementary metadata to flag imputed values.

3. Preserve original temporal representations in *_source_value fields, particularly for partial dates (year-only, year-month) where imputation rules have been applied.

4. Consider timezone requirements for multi-site or time-sensitive studies. If timezone preservation is critical, evaluate database-specific datetime types or auxiliary storage mechanisms outside the standard OMOP schema.

5. Communicate limitations to analysts through data documentation that specifies which datetime fields are reliably populated, what imputation rules were applied, and what temporal precision can be assumed for analytical purposes.

Successful implementations embrace OMOP's date-level precision as the guaranteed minimum while remaining transparent about its constraints and leveraging optional datetime fields where source data supports them. ETL developers ought to codify and publish rules for handling partial dates, analysts ought to incorporate uncertainty into models, and institutions could elect to store high-resolution timestamps in parallel schemas where local research imperatives demand them. By balancing standardisation with explicit provenance, the OMOP community can continue enabling reproducible observational research without obscuring clinically relevant temporal nuance.

Guidance

A Transformation Engine SHALL populate the required OMOP *_date field for every clinical event record it writes, and a Target OMOP Instance SHALL NOT contain a clinical event record with an unpopulated required date field. This applies to the date fields the CDM marks as required; end-date fields that the CDM permits to be NULL are not within its scope.^§f2o-070

Where a required date is derived by imputation from a partial or absent source value, a Transformation Engine SHALL record the imputation by means of an appropriate type concept, and an Implementer SHALL document the imputation rules applied and their effective scope in the ETL documentation.^§f2o-071

Where a FHIR source value carries a time zone offset and the corresponding OMOP *_datetime field is populated, a Transformation Engine SHALL convert the value to a single time zone applied consistently across the instance, and an Implementer SHALL state that time zone in the ETL documentation. The OMOP CDM provides no standard field for a time zone offset, so this guide does not require the original offset to be preserved.^§f2o-072

A Transformation Engine SHOULD populate the optional OMOP *_datetime fields where the FHIR source provides sub-day precision, rather than discarding that precision by populating only the required date field.^§f2o-073

---

Temporal Precision References

[1] Health Level Seven International. FHIR R4 Specification: Data Types. HL7 FHIR Release 4. Available from: http://hl7.org/fhir/R4/datatypes.html

[2] Observational Health Data Sciences and Informatics. OMOP Common Data Model Conventions. Available from: https://ohdsi.github.io/CommonDataModel/dataModelConventions.html

[3] Observational Health Data Sciences and Informatics. OMOP CDM v5.4 Specification. Available from: https://ohdsi.github.io/CommonDataModel/cdm54.html

[4] Observational Health Data Sciences and Informatics. OMOP CDM v6.0 Specification. Available from: https://ohdsi.github.io/CommonDataModel/cdm60.html

[5] PostgreSQL Global Development Group. PostgreSQL Documentation: Date/Time Types. Available from: https://www.postgresql.org/docs/current/datatype-datetime.html

[6] Microsoft Corporation. datetime2 (Transact-SQL) - SQL Server. Microsoft Learn. Available from: https://learn.microsoft.com/en-us/sql/t-sql/data-types/datetime2-transact-sql

[7] Ryan P. Comment on "Timing of time" discussion. OHDSI Forums. 2016 Oct 1. Available from: https://forums.ohdsi.org/t/timing-of-time/1730