Generated Narrative: Requirements fromNarrative These requirements apply to the following actors: FHIR Source System OMOP Target Instance Transformation Engine Terminology Server ETL Implementer f2o-001 SHALL 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 An Implementer SHALL declare the FHIR version or versions of the source data that the transformation is configured to consume. f2o-003 SHOULD 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 A Transformation Engine SHALL preserve the original source code verbatim in the companion *_source_value field. f2o-034 SHALL 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 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 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 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 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 Custom concepts added to a local OMOP instance SHALL use concept_id values at or above 2,000,000,000. f2o-040 SHALL 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 A Target OMOP Instance SHALL conform to the logical model this guide defines for each OMOP table it populates. f2o-091 MAY A Transformation Engine MAY execute the StructureMaps published by this guide, or MAY implement equivalent transformation logic in another technology. f2o-092 SHALL 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 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 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 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 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 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 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 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 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 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 A Target OMOP Instance SHALL disclose which OMOP tables it populates fully, which it populates partially, and which it leaves unpopulated. f2o-132 SHALL 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.
HL7 International / Biomedical Research and Regulation
Conformance statements found throughout the narrative of the IG consolidated into this computable resource for traceability purposes
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.