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

Conformance Statements

Page standards status: Trial-use

Highlight text changes?

The conformance verbs SHALL, SHOULD, and MAY are interpreted per RFC 8174.

This page contains a table listing all the free-text conformance statements found in the IG. This table is provided as a useful summary for implementers for the purpose of evaluating key features and to support testing. However, reading this table alone is insufficient to understand or successfully implement the specification:

1. The table only includes conformance expectations expressed as free text. It does not include the computable expectations represented in capability statements, profiles, value sets, etc.
2. The text text in the table only includes the 'formal' requirement. It does not provide the contextual language around the statement that will be needed for successful explanation. The 'id' of each statement is a hyperlink to the place it appears in the text to assist with gathering the needed context.

The statements are listed in a number of categories:

Category 1. Scope, versioning, and conformance framework

This category establishes what a conformance claim against this guide means: the CDM version targeted, the FHIR versions consumed, the use cases supported, and the actor roles under which a claim is made. It also fixes the interpretation of the conformance verbs used throughout. These statements govern declaration and scope rather than the mechanics of any particular transformation, and they apply to every implementation regardless of which clinical domains it covers.

Category 2. Source FHIR data expectations

This category covers what a transformation may assume about the FHIR data reaching it, and what it does with data that fails those assumptions. It addresses profile declaration, the treatment of optional elements, validation and the disposition of invalid input, and the source units a transformation accepts. The obligations here concern the boundary at which FHIR enters the transformation; the interpretation of the content once admitted belongs to later categories.

Category 3. Identifier handling and privacy

This category governs the treatment of FHIR identifiers and patient identifiable information across the transformation and in the resulting OMOP instance. It distinguishes business identifiers, which carry patient-identifying content, from logical identifiers, which do not, and constrains where each may appear. It also carries the documentation obligations that accompany identifier handling: the privacy and regulatory framework applied, the strategy chosen for each identifier system, and the legal instrument authorizing access to the source data.

Category 4. Code mapping and terminology

This category covers the translation of source codes into OMOP concepts: resolution against the OHDSI Standardized Vocabularies, the division of labor between the concept and source concept fields, preservation of the original code, and the handling of codes with no Standard concept. It also governs selection among competing codes, domain assignment, the custom concept range, and the recording of the vocabulary release under which resolution was performed. Type concepts, which describe provenance rather than clinical content, are treated separately in Category 5.

Category 5. Type concept assignment

This category covers the OMOP type concept fields, which record how a clinical record came to exist rather than what it asserts clinically. The obligations here concern populating those fields with Standard concepts from the Type Concept domain, deriving the value from the resource together with its category and context rather than from the resource type alone, choosing a general concept where the source gives insufficient context, and preserving the distinction between patient-reported and clinician-recorded data.

Category 6. Status, intent, and filtering

This category covers the FHIR elements that qualify whether an event actually occurred, and the consequences of ignoring them. It requires evaluation of status and intent so that unrealized events do not enter the OMOP clinical tables, requires consistent filter rules across incremental loads with any change recorded, and addresses modifier elements that alter clinical interpretation. Because filtering removes data, this category also carries the reporting obligation that makes exclusions visible to operators and downstream consumers.

Category 7. Temporal precision

This category covers dates and times: populating the date fields the CDM requires, recording imputation where a required date is derived from a partial or absent source value, normalizing time zones where a datetime field is populated, and preserving sub-day precision the source provides. The OMOP CDM represents time less richly than FHIR does, so these obligations concern making the resulting loss explicit and consistent rather than preventing it.

Category 8. Granularity and data loss

This category addresses the residue of the transformation: clinical content that FHIR can express and the OMOP CDM cannot. It requires that the points of loss be documented and made available to consumers of the data, that clinically meaningful content without a representable target be emitted to a general domain rather than discarded silently, and that the ETL documentation record mapping decisions, manual interventions, and known limitations. Where Category 7 concerns loss of temporal precision specifically, this category concerns loss of clinical content generally.

Category 9. Logical models and StructureMaps

This category covers the formal transformation artifacts the guide publishes and the target structures they produce. It requires conformance to the logical model defined for each OMOP table populated, permits either execution of the published StructureMaps or equivalent logic in another technology, and requires that departures from published logic be recorded with their rationale. It also states where code-to-concept translation is resolved, since that resolution is not carried by the published artifacts themselves.

Category 10. Traceability, lineage, reproducibility

This category covers the ability to account for how a Target OMOP Instance came to hold what it holds. It concerns the path from a clinical record back to the FHIR resource that produced it, the run metadata identifying the CDM version, vocabulary release, guide version, software version, and execution time for each load, and idempotent re-processing so that repeating a load does not duplicate records. The obligations here support audit and reproduction rather than the correctness of any individual mapping.

Category 11. Terminology server interaction

This category applies only where a FHIR terminology server is part of the architecture, which this guide treats as optional. It requires that a transformation reach the server through standard FHIR terminology operations rather than server-specific interfaces, so that a transformation is not bound to one implementation. It governs cache invalidation against the vocabulary version, and states what a Terminology Server itself claims when it claims conformance to this guide.

Category 12. Testing and coverage

This category covers the demonstration of conformance rather than its substance. It requires that a Transformation Engine pass the reference test suite for the transformations it claims, identifying the independently versioned suite release under which the claim was established, and encourages publication of those results with the guide version and vocabulary release under which the run was performed. It also requires a Target OMOP Instance to disclose which OMOP tables it populates fully, partially, and not at all.

A few other notes:

• While ids start as contiguous, as the specification is updated, it is possible some conformance statements will be removed, which will create a gap in the numbers. This is not an error.
• Ids are not final until published in an official release. At that point, ids will not be changed.
• It is possible for the text of a given rules to change somewhat from one release to another so long as the intention of the rule is the same. If the intent has a significant change, the old rule will be removed and a new one added in its place.
• The actors identified for each statement are defined on the Actors page.

The controls at the top of the table allow filtering the content to particular requirement subsets that may be of interest. As well, a computable representation (XML and JSON) of the requirements can be found here.

Id	Expectation	Actors	Categories	Rule
	SHALL  SHALL NOT  SHOULD  MAY	ETL Implementer  FHIR Source System  OMOP Target Instance  Terminology Server  Transformation Engine	codes  concept  data  dataloss  identifier  models  scope  status  temporal  terminology  testing  traceability
§f2o-001	SHALL	Transformation Engine OMOP Target Instance ETL Implementer	scope	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-002	SHALL	Transformation Engine ETL Implementer	scope	An Implementer SHALL declare the FHIR version or versions of the source data that the transformation is configured to consume.
§f2o-003	SHOULD	Transformation Engine ETL Implementer	scope	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-004	SHALL MAY	ETL Implementer	scope	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.
§f2o-010	SHALL	FHIR Source System Transformation Engine ETL Implementer	data	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.
§f2o-011	SHALL NOT SHALL	Transformation Engine	data	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.
§f2o-012	SHOULD	Transformation Engine ETL Implementer	data	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.
§f2o-013	SHALL	Transformation Engine	data	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.
§f2o-014	MAY	FHIR Source System Transformation Engine	data	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.
§f2o-020	SHALL NOT	Transformation Engine OMOP Target Instance	identifier	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.
§f2o-021	SHALL NOT	Transformation Engine OMOP Target Instance	identifier	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.
§f2o-022	SHALL NOT	Transformation Engine OMOP Target Instance ETL Implementer	identifier	A Target OMOP Instance SHALL NOT contain patient identifiable information, including names, addresses, medical record numbers, and contact details, in any field.
§f2o-023	SHOULD	Transformation Engine OMOP Target Instance	identifier	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.
§f2o-024	SHALL	Transformation Engine OMOP Target Instance	identifier	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.
§f2o-025	SHALL	ETL Implementer	identifier	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.
§f2o-026	SHALL	Transformation Engine ETL Implementer	identifier	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.
§f2o-030	SHALL	Transformation Engine OMOP Target Instance Terminology Server ETL Implementer	codes	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.
§f2o-031	SHALL	Transformation Engine OMOP Target Instance	codes	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.
§f2o-032	SHALL	Transformation Engine OMOP Target Instance	codes	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.
§f2o-033	SHALL	Transformation Engine OMOP Target Instance	codes	A Transformation Engine SHALL preserve the original source code verbatim in the companion *_source_value field.
§f2o-034	SHALL	Transformation Engine ETL Implementer	codes	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.
§f2o-035	SHALL	Transformation Engine	codes	Where a FHIR coding array carries explicit primary or preferred designations, a Transformation Engine SHALL honor them as tiebreakers within the prioritization hierarchy.
§f2o-036	SHALL	Transformation Engine	codes	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.
§f2o-037	SHALL	Transformation Engine	codes	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.
§f2o-038	SHALL SHOULD	Transformation Engine Terminology Server	codes	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.
§f2o-039	SHALL	Transformation Engine OMOP Target Instance	codes	Custom concepts added to a local OMOP instance SHALL use concept_id values at or above 2,000,000,000.
§f2o-040	SHALL	Transformation Engine OMOP Target Instance	codes	A Transformation Engine SHALL record the OHDSI Vocabulary release used to resolve concepts for each ETL run, as part of the run metadata.
§f2o-050	SHALL NOT SHALL	Transformation Engine OMOP Target Instance	concept	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.
§f2o-051	SHALL	Transformation Engine	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.
§f2o-052	SHALL	Transformation Engine	concept	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.
§f2o-053	SHALL	Transformation Engine OMOP Target Instance ETL Implementer	concept	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.
§f2o-060	SHALL NOT SHALL	Transformation Engine ETL Implementer	status	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-061	SHALL	Transformation Engine ETL Implementer	status	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-062	SHOULD	Transformation Engine ETL Implementer	status	A Transformation Engine SHOULD emit a run-level report of resources excluded by filter, recording counts by resource type and exclusion reason.
§f2o-063	SHALL NOT SHALL	Transformation Engine	status	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-070	SHALL NOT SHALL	Transformation Engine OMOP Target Instance	temporal	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-071	SHALL	Transformation Engine ETL Implementer	temporal	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-072	SHALL	Transformation Engine OMOP Target Instance	temporal	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-073	SHOULD	Transformation Engine OMOP Target Instance	temporal	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-080	SHALL	Transformation Engine ETL Implementer	dataloss	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-081	SHOULD	Transformation Engine OMOP Target Instance	dataloss	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-082	SHALL	Transformation Engine ETL Implementer	dataloss	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-090	SHALL	Transformation Engine OMOP Target Instance	models	A Target OMOP Instance SHALL conform to the logical model this guide defines for each OMOP table it populates.
§f2o-091	MAY	Transformation Engine ETL Implementer	models	A Transformation Engine MAY execute the StructureMaps published by this guide, or MAY implement equivalent transformation logic in another technology.
§f2o-092	SHALL	Transformation Engine ETL Implementer	models	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-093	SHALL	Transformation Engine Terminology Server ETL Implementer	models	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-100	SHOULD	Transformation Engine OMOP Target Instance ETL Implementer	traceability	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-102	SHALL	Transformation Engine OMOP Target Instance ETL Implementer	traceability	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-103	SHOULD	Transformation Engine OMOP Target Instance	data status	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-110	SHALL	Transformation Engine Terminology Server	terminology	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.
§f2o-111	SHALL SHOULD	Transformation Engine Terminology Server	terminology	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.
§f2o-112	SHALL	Terminology Server ETL Implementer	terminology	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.
§f2o-120	SHALL	Transformation Engine OMOP Target Instance ETL Implementer	testing	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-121	SHOULD	Transformation Engine ETL Implementer	testing	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-122	SHALL	Transformation Engine OMOP Target Instance ETL Implementer	testing	A Target OMOP Instance SHALL disclose which OMOP tables it populates fully, which it populates partially, and which it leaves unpopulated.
§f2o-132	SHALL	ETL Implementer	identifier	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.