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.

An Implementer SHALL declare the FHIR version or versions of the source data that the transformation is configured to consume.

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.

An Implementer SHALL declare which use cases the transformation supports. The declared set MAY include any of the use cases described on this page, other use cases not described here, or a stated combination, so that the scope of a given FHIR-to-OMOP transformation is stated explicitly rather than inferred.

An Implementer SHALL declare which input FHIR profiles the transformation accepts. The declared set could be any FHIR profiles the transformation is built to consume, whether the International Patient Access and US Core profiles this guide curated its maps against, other published profiles, or base FHIR resources conforming to no profile beyond the resource definitions.

A Transformation Engine SHALL rely only on the elements guaranteed by what it has declared it accepts, whether a profile or a base resource definition, and SHALL NOT assume the presence of an element that a conformant source is permitted to omit. This is a constraint on assumptions about optional content, not an obligation to handle content beyond the transformation's declared scope.

A Transformation Engine SHOULD validate incoming resources against the profiles the transformation declares it accepts, and SHOULD handle a validation failure by a documented disposition, rejecting or quarantining the resource rather than admitting it unvalidated. The disposition of failed input SHOULD be recorded so that the volume and reasons for failure are visible to operators and to consumers of the target.

A Transformation Engine SHALL support ingestion of both singleton resources and Bundles, since both forms are produced by conformant FHIR servers under ordinary retrieval patterns and a transformation restricted to one form cannot consume the other without an intermediary. Where a Bundle is the source unit, its Bundle.type SHALL be one of document, collection, or message.

A Transformation Engine MAY support ingestion of Bulk Data NDJSON exports; this is not required, because Bulk Data Access is itself an optional capability for FHIR servers and not all data holders expose it, but implementers building population-scale OMOP instances ought to expect to encounter it.

A Transformation Engine SHALL NOT store FHIR business identifier values (Resource.identifier) in OMOP _source_value fields, and a Target OMOP Instance SHALL NOT contain business identifier values in those fields.

A Transformation Engine SHALL NOT derive OMOP integer primary keys from FHIR business identifiers (Resource.identifier). Where primary keys are derived from FHIR source data rather than generated independently, the FHIR logical identifier (Resource.id combined with the resource type) is the appropriate source.

A Target OMOP Instance SHALL NOT contain patient identifiable information, including names, addresses, medical record numbers, and contact details, in any field.

An Implementer SHOULD maintain an external mapping table linking OMOP-generated identifiers to the originating FHIR logical identifier ([ResourceType]/[Resource.id]) where traceability from OMOP records back to source resources is required.

Where an external mapping table is maintained, it SHALL reside outside the OMOP schema and SHALL be governed by access controls distinct from those governing the OMOP instance itself.

An Implementer SHALL document a privacy and regulatory assessment for each identifier system encountered in the source data, identifying the framework applied, whether HIPAA Safe Harbor, Expert Determination, GDPR, or an equivalent, and the determination reached.

An Implementer SHALL document, for each identifier system encountered, which handling strategy was applied, whether surrogate key mapping, external storage, or exclusion, and record that determination in the ETL documentation.

A Transformation Engine SHALL resolve concept assignments against the OHDSI Standardized Vocabularies, verifying concept existence, Standard concept status, and domain assignment for each source code it maps.

A Transformation Engine SHALL populate OMOP *_concept_id fields only with Standard concepts, and SHALL record a non-Standard source concept in the companion *_source_concept_id field rather than in the *_concept_id field.

Where a source code has no Standard OMOP concept and no custom concept is created for it, a Transformation Engine SHALL populate the corresponding *_concept_id field with 0.

A Transformation Engine SHALL preserve the original source code verbatim in the companion *_source_value field.

Where multiple codes are present for a single clinical idea, a Transformation Engine SHALL apply the Code Prioritization Framework described on this page, and an Implementer SHALL document any departure from it.

Where a FHIR coding array carries explicit primary or preferred designations, a Transformation Engine SHALL honor them as tiebreakers within the prioritization hierarchy.

Where a coding array carries both a parent concept and a more specific child concept from the same code system, a Transformation Engine SHALL select the more specific concept.

A Transformation Engine SHALL assign the OMOP domain from the domain_id of the resolved concept rather than from the FHIR resource type, and a Target OMOP Instance SHALL store each clinical record in the domain table its concept's domain_id indicates.

A Transformation Engine SHOULD resolve concepts through the ConceptMap/$translate and CodeSystem/$lookup operations of a FHIR terminology server rather than through a crosswalk hard-coded into the transformation. Where a static crosswalk is used instead, an Implementer SHALL record its provenance and the vocabulary release from which it was derived.

Custom concepts added to a local OMOP instance SHALL use concept_id values at or above 2,000,000,000.

A Transformation Engine SHALL record the OHDSI Vocabulary release used to resolve concepts for each ETL run, as part of the run metadata.

A Transformation Engine SHALL populate every OMOP *_type_concept_id field with a Standard concept from the Type Concept domain, and a Target OMOP Instance SHALL NOT contain a clinical record with an unpopulated or non-Standard type concept.

A Transformation Engine SHALL derive the type concept from the FHIR resource type together with the category and context elements the resource carries, rather than from the resource type alone.

Where the source does not carry sufficient context to identify a specific type concept, a Transformation Engine SHALL select the most general applicable Type Concept rather than assigning a specific one by inference.

Where a source record is patient-reported, a Transformation Engine SHALL assign a type concept distinguishing it from clinician-recorded data, and a Target OMOP Instance SHALL preserve that distinction.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

A Target OMOP Instance SHALL conform to the logical model this guide defines for each OMOP table it populates.

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

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.

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.

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

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.

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.

Where a Transformation Engine resolves concepts through a FHIR terminology server, it SHALL do so through the standard ConceptMap/$translate and CodeSystem/$lookup operations rather than through server-specific interfaces, so that a transformation is not bound to a particular server implementation.

A Transformation Engine SHOULD cache terminology server responses, and where it does so SHALL bind the cache invalidation policy to the OHDSI Vocabulary version, such that entries computed under one vocabulary version are not read under another.

A Terminology Server claiming conformance to this guide SHALL expose the OHDSI Standardized Vocabularies as FHIR CodeSystem and ConceptMap resources, and SHALL report the vocabulary release it is serving in the version element of its responses.

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.

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.

A Target OMOP Instance SHALL disclose which OMOP tables it populates fully, which it populates partially, and which it leaves unpopulated.

An Implementer SHALL document the legal instrument governing access to the source FHIR data, whether a business associate agreement, an IRB approval or waiver, a data use agreement, or an equivalent, together with any constraint it places on identifier retention, linkage, or re-identification.