Map FHIR resources to OMOP CDM v5.4
/fhir2omop/createMaps a FHIR R4 resource or Bundle to OMOP CDM v5.4 rows, grouped by
destination table in tables. The request must include at least one
top-level Patient. Unsupported resource types are ignored; supported
resources that cannot produce a row are reported in dropped.
All shaped rows remain in tables, including partial rows and clinical
rows with uncertain status or unresolved primary concepts. Use
rows_for_review to identify the latter, mappings to inspect concept
resolution, and diagnostics to understand unusable data or links.
Resource-specific context arrays preserve source information linked to
the emitted rows; see the response schemas for their fields and outcomes.
Rows may lack CDM-required fields when the source cannot supply them. Before loading a CDM dataset, callers must handle incomplete rows, assign durable IDs, and remap primary and foreign keys together. Returned IDs start at 1 within each table and are local to one response.
The source format is FHIR R4 v4.0.1 and the output follows OMOP CDM v5.4. The informative Vulcan FHIR-to-OMOP IG provides an R5 baseline adapted here to R4 source fields. Full FHIR or US Core profile conformance is not validated.
Resource coverage
| FHIR source | OMOP output |
|---|---|
| Patient | person; deceased status can produce death, the first address can produce location, and multiple resolved races produce race observation rows |
| Location | location and care_site |
| Organization | care_site; its first address can produce location |
| HealthcareService | care_site |
| Practitioner, PractitionerRole | provider, with role context retained separately |
| Encounter | visit_occurrence, or visit_detail for supported explicit components |
| Specimen | specimen, requiring an explicit Patient subject |
| DeviceUseStatement | device_exposure, using referenced Device details |
| Condition | Domain-selected clinical table; default condition_occurrence |
| Procedure | Domain-selected clinical table; default procedure_occurrence |
| MedicationRequest, MedicationStatement, MedicationAdministration, MedicationDispense, Immunization | Domain-selected clinical table; default drug_exposure |
| Observation | Domain-selected clinical table; numeric values default to measurement, other values to observation |
| AllergyIntolerance | Contextual allergy observation or another supported clinical table, excluding drug/device exposure; default observation |
| Medication, Device | Reference data; no independent row |
One request-local observation_period is derived per person with qualifying
dates. It spans visit/clinical rows not indexed for review, plus Specimen and Death rows,
including selected source end dates even when the destination has no end
column. Dates from rows_for_review do not expand it. This period is not
evidence of enrollment or complete data capture.
Concept resolution and placement
Use vocab_version to select the vocabulary release; omitted or empty
values use the default release. The response reports the release used
when vocabulary resolution occurred. Select a release explicitly for
reproducibility.
Resolved primary clinical concepts determine placement in
condition_occurrence, procedure_occurrence, drug_exposure,
device_exposure, measurement, or observation. For Observation,
numeric versus nonnumeric values break a tie between Measurement and
Observation placement. An unresolved or destination-invalid concept keeps
the resource's default table, concept ID 0, and UNMAPPED status.
Clinical records produce one row each, except the explicit DeviceUseStatement
Timing events described below; multiple vocabulary targets do not expand
a record into multiple rows. Note destinations and vocabulary Maps to value
decomposition are unsupported.
Source timing and eligibility apply regardless of the selected table.
Source-specific values populate only compatible columns: Condition status
in condition_occurrence, medication supply/dosage and Immunization lot
details in drug_exposure, and Observation values in measurement or
observation. Coded routes on other tables are resolved as mapping context;
Observation values on other tables are preserved without concept resolution.
Those entries omit omop_field and have selected: false.
Supported primary clinical concepts, specimen material, and unresolved coded Observation results can use semantic mapping from descriptive text. CodeableConcept text takes precedence over coding display; bare codes do not supply descriptions. Deterministic mappings take precedence, and ambiguous or domain-mismatched results are not reinterpreted. Inference requires one validated, equivalent active standard concept valid for the destination; a broader crosswalk target does not validate a suggestion. Units, routes, visits, demographics, specialties, collection sites, and contextual allergy findings follow their separate policies.
Inferred results have resolution.semantic_mapping.status: MAPPED in
their linked mappings; unsuccessful attempts report UNMAPPED with
concept ID 0. Original coding is preserved and no source coding is invented.
Successful inference does not remove uncertain-status review reasons.
Use mapping row links to filter inferred results if needed.
Clinical *_source_value fields contain the selected bare code, or text
for text-only inputs. The selected mapping preserves its coding provenance.
Unresolved source concept IDs are 0, except allergy rows can retain a known
original source identity even when the finding is unresolved. Known coding
system OIDs, bare or urn:oid:, resolve like their canonical URLs and are
reported canonically in coding mappings. Quantity unit mappings preserve
the supplied system spelling. Unknown OIDs remain unchanged.
References and eligibility
Top-level references resolve only within the request, by exact Type/id
or Bundle fullUrl, including URNs and absolute URLs. Contained references
are supported for medication lookup, DeviceUseStatement.device, and
PractitionerRole.practitioner. The latter also supports request-local
identifier matching. Resources are not fetched remotely.
Clinical subject/patient references must resolve unambiguously to a supplied Patient. If the reference is absent, a sole Patient can supply attribution, except for Specimen, DeviceUseStatement, and MedicationDispense, which require explicit subjects. Unusable explicit patient references drop the resource. Unusable optional links leave the link unset with a diagnostic while retaining otherwise eligible rows. Every nonzero structural foreign key targets a row in the same response, and clinical visit links must belong to the same patient.
Eligibility follows the source resource's status policy. Other than the absent/uncertain statuses explicitly supported below, missing or unrecognized required statuses drop the resource. Entered-in-error and explicitly non-performed events do not produce positive clinical-event rows.
| Resource | Eligible status or evidence | Retained for review |
|---|---|---|
| Condition | Absent or confirmed canonical-HL7 verificationStatus; refuted and entered-in-error are dropped | Unconfirmed, provisional, differential, or unreadable supplied verificationStatus |
| Encounter | arrived, triaged, in-progress, onleave, finished; planned, cancelled, and entered-in-error are dropped | Unknown, missing, or unreadable status |
| Procedure | completed, stopped | Explicit unknown status |
| MedicationRequest | active, on-hold, completed, stopped, with authorizing intent: order, original-order, reflex-order, filler-order, or instance-order; doNotPerform excludes the request | None |
| MedicationStatement | active, completed, stopped, on-hold | Explicit unknown status |
| MedicationAdministration | completed, in-progress, stopped, or on-hold; on-hold also requires a usable effective start, including partial dates | None |
| MedicationDispense | completed, including partial fills; stopped also requires a valid whenHandedOver, including partial dates | None |
| Immunization | completed | None |
| Observation | final, amended, corrected | Explicit unknown status |
| AllergyIntolerance | Absent, unconfirmed, or confirmed canonical-HL7 verificationStatus; invalid supplied type/category drops the resource | None |
| Specimen | Absent, available, unavailable, unsatisfactory | None |
| DeviceUseStatement | active, completed, stopped, on-hold | None |
Condition clinical course is not a diagnosis-role mapping. Retained uncertain
rows preserve their supplied statuses without asserting that an event occurred
or medication was taken. Eligible clinical rows with primary concept 0 are
also indexed for review; unresolved secondary units, routes, or result concepts
alone do not index a mapped row. Administrative/demographic, Specimen, and
Death rows are excluded from the review index. See rows_for_review for
filtering and linked-visit requirements.
Device placement additionally requires eligible use evidence. MedicationRequest,
AllergyIntolerance, uncertain-status records, and explicit negative Observation
results cannot produce device exposure. Negative evidence includes false,
SNOMED Negative/Known absent/No, and NEG from
http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation.
Reporting actors such as recorder, asserter, or informationSource do not
supply a device event's treating provider.
Timing
Dates require at least day precision and use the source calendar date.
Datetimes are present only when time of day was supplied, as local wall-clock
time without a UTC offset, retaining fractional seconds to microseconds.
For example, 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00.
A timestamp without a timezone is read as local time.
A valid year/month-only date leaves date and datetime unset and stops a fallback chain. Malformed dates and unsupported timing forms are ignored so a later source can be used. Dates are not imputed from other resources. Specimen, DeviceUseStatement, and MedicationDispense report unusable timing through diagnostics; otherwise missing dates usually retain partial rows. The effective-start and handover eligibility requirements above still apply.
| Source | Start/date source, in priority order | End or additional timing |
|---|---|---|
| Patient | birthDate supplies year/month/day components; deceasedDateTime supplies death timing | birth_datetime is not set; boolean-only deceased status supplies no death date |
| Practitioner | birthDate supplies year_of_birth | — |
| Encounter | period.start | period.end |
| Condition | onsetDateTime, onsetPeriod.start, recordedDate | abatementDateTime or abatementPeriod.end |
| Procedure | performedDateTime or performedPeriod.start | performedPeriod.end |
| Observation | effectiveDateTime, effectivePeriod.start, effectiveInstant | — |
| AllergyIntolerance | recordedDate, onsetDateTime, onsetPeriod.start | — |
| MedicationRequest | authoredOn, as prescription timing | No exposure end; validity period is not exposure duration |
| MedicationStatement | effectiveDateTime or effectivePeriod.start | effectivePeriod.end; dateAsserted is not exposure timing |
| MedicationAdministration | effectiveDateTime or effectivePeriod.start | A single dateTime also sets the end; otherwise effectivePeriod.end |
| MedicationDispense | whenHandedOver | No exposure end, including from daysSupply; whenPrepared is not a fallback |
| Immunization | occurrenceDateTime | The same dateTime also sets the end; expirationDate is not used |
| Specimen | collection.collectedDateTime or collection.collectedPeriod.start | Period end and receivedTime are not collection-start fallbacks |
| DeviceUseStatement | timingDateTime, independent timingPeriod boundaries, or one start per timingTiming.event | No end is inferred for dateTime/Timing events; repeat-only schedules retain an undated row |
End columns are populated only where supported by the destination table.
For medication rows, verbatim_end_date comes only from an explicit
Period.end, not a single-event end.
Providers and patient demographics
Administrative links are best-effort. Patient.managingOrganization is a
record custodian and does not supply a care site. Address.country resolves
to location.country_concept_id; CMS Place of Service codings in Location.type
resolve to care_site.place_of_service_concept_id. Practitioner recorded
gender is separate from Person demographics: male/female can resolve to
Provider Gender concepts; other, unknown, or absent values stay 0.
Within a request, Practitioners and role-only providers sharing one confirmed individual NPI (Type 1) merge only when their supplied rendered name, recorded gender, DEA identifier, and parsed birth year are compatible. The first name entry and first non-empty DEA identifier are used; supplied identity values compare exactly. Missing attributes can enrich a compatible row. A conflict keeps the entire NPI group separate with linked diagnostics. Multiple distinct NPIs on a Practitioner also prevent merging and leave npi unset. No merge occurs across requests.
NPI classification trims whitespace and validates ten digits and the NPI check digit; returned source values and merge comparisons preserve the supplied spelling. Known individual NPIs remain usable for historical care when deactivated. An invalid or unconfirmed NPI retains a source-scoped Practitioner without npi, with an UNRESOLVED diagnostic at identifier. No live public registry lookup is performed; classification failures return HTTP 500. Accepted NPI system forms, missing-value markers, and source-identity semantics are defined in ProviderRow.
A PractitionerRole can alias a supplied Practitioner by structural reference, unambiguous parent-contained reference, or identifier match to a top-level Practitioner. Supplied Reference.type must be Practitioner. NPI identifier matching requires a confirmed individual NPI and accepts the NPI system aliases; other identifiers match exactly. Unusable or ambiguous references have diagnostics. A resolved Practitioner's identity takes precedence over the role's identifiers.
Without a resolvable supplied Practitioner, a role requires one confirmed individual NPI in PractitionerRole.identifier or practitioner.identifier to emit a provider. NPIs from both fields must agree exactly. A usable logical NPI reference needs no supplied Practitioner and produces no missing-Practitioner diagnostic. Role-only providers share the NPI grouping rules; names, gender, and birth information are not invented. provider_role_contexts preserves every emitted role's specialty and care-site context, including when roles share a provider.
Provider exclusions are reported in dropped:
- provider_npi_is_organization: a top-level Practitioner or role-only provider is identified by an organization NPI (Type 2).
- provider_role_requires_individual_npi: a role has neither a usable Practitioner nor a confirmed individual NPI.
- provider_role_conflicting_npis: a role without a usable Practitioner supplies multiple distinct NPIs across its identifier fields.
- provider_practitioner_is_not_individual: a role resolves to an organization Practitioner.
Clinical rows remain eligible when a provider is omitted; their provider links stay unset, with UNRESOLVED diagnostics pointing to the provider's dropped entry.
Each role specialty resolves independently from supported codings, with
deterministic explicit-text fallback for text-only entries or complete codings
from unsupported systems. Incomplete/malformed codings or recognized systems
block text fallback; coding displays do not supply fallback text. Complete
unsupported companions do not block agreeing supported codings. Unsupported
systems must be well-formed absolute URIs without whitespace, credentials,
or fragments. specialty_concept_id is populated only when at least one
specialty is supplied and every distinct input resolves to the same standard
Provider concept; otherwise it stays 0. Each role's source and outcome remain
in mappings, including repeated inputs. Specialty mappings have selected: false;
see SpecialtyResolution for per-coding evidence and MappingResolution.via for
the reported matching route.
Patient sex at birth, race, and ethnicity use these US Core 6.1.0 extension structures/value sets on any Patient; a US Core profile declaration is not required. Other demographic extensions are ignored.
| Demographic | Extension URL | Supported value source |
|---|---|---|
| Birth sex | http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex | valueCode, using http://hl7.org/fhir/us/core/ValueSet/birthsex |
| Race | http://hl7.org/fhir/us/core/StructureDefinition/us-core-race | ombCategory, using http://hl7.org/fhir/us/core/ValueSet/omb-race-category |
| Ethnicity | http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity | ombCategory, using http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category |
- A supplied birth-sex extension takes precedence: M/F resolve, while unknown, unsupported, or conflicting values, or an extension without valueCode, leave concept 0 without falling back to Patient.gender. Without a birth-sex extension, male/female administrative gender is used under the OMOP sex-at-birth convention; other/unknown remain 0.
- One distinct resolved race sets the Person race concept. Multiple races use
1546847(More than one race) and one observation per race: concept4013886(Race), type32817, and the race invalue_as_concept_id. The category code isvalue_source_value; observation_source_value and observation_date are absent. Loaders must supply their own required-date policy. - One non-null ethnicity category can resolve; conflicting categories leave
concept 0. Multiple-ethnicity observations are not produced. Race/ethnicity
null flavors are ignored, and detailed codes/text are preserved without
resolution. Source codes are joined with
|in source order, falling back to extension text when no code exists. - Mappings preserve supplied demographic codes and indicate which were selected; overridden administrative gender is unselected. Conflicting birth sex/ethnicity and birth sex without valueCode also have diagnostics. Summary counts follow the field-level rules in Summary. Demographics are not inferred from other data.
Allergies and observations
Coded AllergyIntolerance statements use original codings, optional type, and
category to resolve an Observation finding and the causative substance
independently. A Drug-domain substance can be a value without implying drug
exposure or medication allergy. Contextual findings report MAPPED and
resolution.via: CONTEXTUAL; original source concept identity is retained.
The contextual finding policy is:
| Supplied type | Medication, optionally with biologic | Food alone | Other or unknown categories |
|---|---|---|---|
| allergy | Allergy to drug (439224) | Allergic disposition (43530807) | Allergic disposition (43530807) |
| intolerance | Intolerance to drug (4240582) | Intolerance to food (4340252) | Intolerance to substance (36684107) |
| Absent | Propensity to adverse reactions to drug (4305025) | Propensity to adverse reactions to food (4303802) | Propensity to adverse reaction (4172024) |
Selected findings must be active standard concepts in the requested release. Limited reviewed substance mappings can supply an absent category; Drug-domain membership alone does not. An absent type remains absent. Supported existing findings and negative statements retain their meaning. Conflicting or ambiguous evidence leaves the affected concept unresolved; the finding and substance can resolve independently, so partial rows are retained. In particular, category conflict need not prevent resolution of a single identified substance. Unsupported contextual sources retain domain-based placement, excluding drug/device exposure, with contextual coverage reported separately.
resolution.allergy preserves supplied context and interpretation evidence;
finding and substance mappings link to the same row and separate fields.
Text-only statements follow primary semantic mapping. Reaction-substance
fallback and Maps to value decomposition are not applied. Invalid supplied
type/category drops that AllergyIntolerance with allergy_type_unrecognized
or allergy_category_unrecognized, while other resources continue.
For Observation rows placed in Measurement or Observation, numeric Quantity,
Integer, and numeric-looking String values populate value_as_number.
Comparators are represented only by Measurement.operator_concept_id.
valueQuantity.value and valueInteger accept JSON numbers. Finite numeric
valueString results are interpreted equivalently, including optional
comparators, while preserving the original text in value_source_value.
Other non-coded values populate Observation.value_as_string or
Measurement.value_source_value. Coded valueCodeableConcept results resolve
to value_as_concept_id using active standard concepts from any domain;
the selected code becomes value_source_value. Unmapped coded results use 0,
and an Observation's value_as_string remains empty for coded results.
Text-only result concepts remain text without concept resolution.
Other unsupported value[x] forms and components do not produce separate values.
Quantity units on Measurement, Observation, and Specimen use exact,
case-sensitive coded UCUM, including accepted OID spellings. Matching may be
direct or through an active OMOP Maps to relationship; there is no UMLS bridge,
text guessing, alias correction, or numeric conversion. An absent unit is null;
a supplied unit without a valid standard Unit match is 0. Explicit UCUM 1
is supplied unit evidence. Quantity.code supplies unit_source_value when present,
otherwise Quantity.unit. Unit mappings preserve Quantity.system/code/unit in
source_system/source_code/source_name. See unit field schemas for source-concept
and resolution metadata.
Observation units on other clinical destinations are not resolved separately.
Specimens and devices
Specimen requires an explicit top-level Patient subject using the shared reference rules; supplied Reference.type must identify Patient. Missing collection timing or material retains a partial row with diagnostics. Material resolves against Specimen, collection quantity units against Unit, and collection.bodySite against Spec Anatomic Site. Missing material produces concept 0 without a terminology outcome; supplied unmapped material has its own outcome. Text-only sites retain text and concept 0 without a suggestion. Absent unit/site concepts are null; supplied unmapped values are 0.
Specimen quantity is copied without conversion when nonnegative and free of
a comparator; unusable quantities are omitted with diagnostics. Missing,
partial, invalid, or conflicting collection choices leave timing unset.
Parent/derived specimens require their own Patient and do not inherit missing
material/dates. Parent and Measurement-to-Specimen links are not represented.
specimen_source_contexts retains availability, identities, and original timing;
SpecimenRow describes source-ID precedence and required-date limitations.
For US Core Specimen 7.0.0 inputs, only the fields described here are mapped;
full profile conformance is not validated.
DeviceUseStatement requires an explicit emitted Patient and supports request-local Device references, including unambiguous contained Devices. Missing or unusable Device details retain a known-patient exposure with concept 0 and diagnostics. Missing type evidence has no terminology outcome; supplied unmapped type evidence has one. Inventory-only Devices produce no exposure.
Each timingTiming.event produces a separate start-only exposure, even if the event date is unusable; events plus repeat rules produce only those event rows. A repeat-only schedule retains one undated row without expanding recurrence. Competing timing choices or a provably reversed Period leave both bounds unset. Partial or malformed individual dates leave their columns absent. RecordedOn and status do not supply missing use dates.
Device exposure contexts group row links and source evidence per source record, with event_index for Timing events. Distinct records remain separate, including overlapping use and matching device/source identifiers; row counts do not count distinct physical devices. An unambiguous UDI-DI supplies unique_device_id; competing identifiers and production details remain in context, and production_id is unset. Device source values identify clinical/type coding, not inventory IDs.
Device quantity defaults to 1 when quantity evidence is absent. Clinical quantities, doses, rates, and numeric Observation results, including numeric valueString, do not establish device counts and leave quantity omitted. device_exposure_contexts retains the original evidence; quantity_basis and diagnostics explain the result. Timing repeat count does not establish quantity. Device unit IDs are always null. DeviceUseStatement uses EHR type 32817 and has no provider or visit links; routed clinical rows retain eligible performer and same-patient visit links.
Medication and drug quantities
MedicationRequest, MedicationStatement, and MedicationAdministration accept inline medicationCodeableConcept, a request-local Medication reference, or display-text fallback when a reference cannot resolve. A reference resolving to a non-Medication is not rescued by display. MedicationDispense requires usable inline code/text or a reference resolving to a Medication with usable code/text; both choice forms together drop the dispense. Display-only or unresolved references do not establish dispensing medication identity.
For MedicationDispense, context links to a supplied same-patient Encounter, and the first resolvable Practitioner/PractitionerRole performer supplies the provider. Authorizing prescriptions provide validated request-local linkage only; dispensing values come from the dispense. Orders, dispenses, and administrations emit independently without deduplication by drug. Comparable handover/preparation dates proving handover before preparation leave start timing unset with a conflict diagnostic. A completed dispense can remain partial without usable handover, and no exposure end is derived. For US Core MedicationDispense 7.0.0 inputs, only the fields described here are mapped; full profile conformance is not validated.
For drug_exposure output:
- MedicationRequest.dispenseRequest.numberOfRepeatsAllowed supplies refills; its positive whole-day expectedSupplyDuration supplies days_supply.
- MedicationDispense.daysSupply requires positive whole coded UCUM
ddays, without a supplied comparator. Missing supply is allowed; unsupported values are omitted with diagnostics. It does not derive exposure end or refills. - Non-empty dosage text supplies newline-joined sig. Coded dosage/Immunization routes resolve against Route; conflicting routes remain unset, while codings shared by all dosage instructions can select a route. Immunization.lotNumber supplies lot_number.
- MedicationRequest uses type 32838 (EHR prescription), MedicationDispense uses 32825 (EHR dispensing record), and other current sources use 32817 (EHR). These are provenance classifications, not proof of medication consumption.
Direct quantities are supported at MedicationRequest.dispenseRequest.quantity, MedicationDispense.quantity, MedicationAdministration.dosage.dose, and Immunization.doseQuantity. Values must be positive finite numbers without a supplied comparator and with a supported system/code. Rates and MedicationStatement dosages do not establish a supported total quantity.
The selected drug must be Clinical Drug or Branded Drug with one active, supported dose form and sufficient unambiguous vocabulary evidence.
| Quantity policy | Supported RxNorm dose forms | Output meaning |
|---|---|---|
| fixed_dose_form_count | Oral Tablet (317541), Oral Capsule (316965), Extended Release Oral Tablet (316945), Extended Release Oral Capsule (316943), Delayed Release Oral Tablet (10312), Delayed Release Oral Capsule (316995) | Count of the selected form, copied from a matching coded count or derived from ingredient amount and per-unit strength; only whole, half, or third units are supported |
| clinical_injection_ingredient_amount | Injectable Solution (316949), Injectable Suspension (316950), Injection (1649574) | Ingredient amount in result_unit, copied/converted from ingredient amount or derived from volume and validated per-unit concentration |
Fixed-form counts accept TAB/CAP under
http://terminology.hl7.org/CodeSystem/v3-orderableDrugForm, or
{tbl}/{Capsule} under http://unitsofmeasure.org, matching the selected
tablet/capsule family. Explicit counts do not require ingredient strength,
including for combination products. Strength-based conversions require one
ingredient strength; concentration-based strength cannot derive fixed-form
counts. Minor arithmetic roundoff is normalized to a supported fraction.
Ingredient amounts and injection volumes require coded UCUM, including its
bare/OID-URN forms. Exact vocabulary-backed strength units, including [U],
are accepted. Differing-unit conversion is limited to compatible mass
(ug, mg, g), volume (uL, mL, L), and milliequivalent
(meq, 10*-3.eq) groups. Codes are case-sensitive; free text, generic count
annotations, unsupported units, and cross-dimensional conversions are not
interpreted. Injection volume conversion requires explicit, consistent per-unit
concentration evidence; a missing denominator alone does not establish it.
Use quantity_transformations.result_unit: injection output is already the
ingredient amount and must not be multiplied by concentration again.
Unsupported formulations, quantified products, packs/prefilled syringes, unsupported fractions, or insufficient/ambiguous evidence leave quantity unset while retaining the row. QuantityTransformation.reason distinguishes omissions. The audit records each supplied direct quantity, including null/malformed input, on an emitted drug_exposure row as DIRECT, DERIVED, or OMITTED. Missing quantities, dropped resources, other destination tables, and unsupported dosage/rate paths have no audit entry. Result units, evidence, and intermediate unit conversion use the response vocabulary release; quantity audits do not affect terminology counts in Summary.
Encounter classification and components
Encounter classifications require both Coding.system and Coding.code.
The following class codes are supported under
http://terminology.hl7.org/CodeSystem/v3-ActCode or
http://hl7.org/fhir/v3/ActCode:
| Class | Visit concept |
|---|---|
| IMP | Inpatient Visit (9201) |
| AMB | Outpatient Visit (9202) |
| EMER | Emergency Room Visit (9203) |
| VR | Telehealth (722455) |
| HH | Home Visit (581476) |
OBSENC has no direct class mapping. Other class/type codes require a valid standard Visit mapping in the selected release. Mapped class takes precedence; a disagreeing mapped type produces a conflict diagnostic. If class is missing or unmapped, type supplies the Visit only when all mapped type classifications agree. Codings within one type are alternative encodings. Unresolved or conflicting selection leaves concept 0 without defaulting to outpatient. Source values/concepts identify the selected original classification.
An explicit Encounter.partOf can produce a child visit_detail linked to a parent visit_occurrence when both are supplied top-level Encounters, explicitly reference the same unambiguous Patient, have eligible known statuses, and form a supported two-level parent/child structure. Supplied reference types must agree. Details use their own timing, classification, and supported provider/care-site links without inheriting parent values.
| Compatibility assessment | Output for the child |
|---|---|
| COMPATIBLE | visit_detail, including identical or parent-ancestor/detail-descendant Visit concepts |
| UNKNOWN | Partial visit_detail with an unsupported diagnostic explaining the limitation |
| INCOMPATIBLE | Independent visit_occurrence with a conflict diagnostic |
visit_component_contexts links each assessment to the final child row and
reports its concepts and vocabulary release. Assessment unavailability or
malformed results fail the request with HTTP 500. An UNKNOWN assessment alone
does not index a mapped row for review; primary concept 0 still does.
Classifications and source dates are preserved in all outcomes.
Period comparisons require matching precision and timezone presence; offset timestamps compare as instants. Timing that proves reversed or disjoint periods prevents grouping. Incomplete or incomparable timing can retain grouping with diagnostics. Overlapping periods may extend outside the parent, with a conflict diagnostic and no clipping or expansion. Unsupported references, patient/status relationships, cycles, and deeper hierarchies retain independently eligible standalone visits. Encounters with unknown, missing, or unreadable status do not qualify as components. ClassHistory, location-period segmentation, admission/discharge concepts, and inferred sequencing are not mapped.
A clinical reference to a detail supplies both visit_detail_id and its parent visit_occurrence_id; a parent reference supplies only the visit ID. These links apply across all supported clinical destinations. Failed optional references retain the clinical row without the link. DeviceUseStatement has no R4 Encounter reference and receives neither link; dates alone never establish links.
Body parameters
OMOP vocabulary release to use for coded concept resolution. If
omitted or empty, the API uses its default release (v20260829).
Specify a release explicitly when reproducibility matters. The response's
vocab_version, when present, identifies the release used.
A single FHIR R4 resource or Bundle containing at least one top-level Patient. Supported row-producing sources: Patient, Location, Organization, HealthcareService, Practitioner, PractitionerRole, Encounter, Specimen, DeviceUseStatement, Condition, Procedure, MedicationRequest, MedicationStatement, MedicationAdministration, MedicationDispense, Immunization, Observation, and AllergyIntolerance. Medication and Device supply referenced details without independent rows; unsupported resource types are ignored.
Each concept field submitted for vocabulary resolution supports at most 1,000 source items: each coding and any non-empty PractitionerRole.specialty text (including whitespace-only text) count as one item. Exceeding the per-field limit rejects the entire request with HTTP 400.
FHIR resources mapped to OMOP CDM v5.4
Response fields
OMOP CDM v5.4 rows grouped by destination table. IDs are sequential and
scoped to one response; they are not stable keys across requests.
Fields with no value are unset (omitted from the row), except concept
IDs reported as 0 and the following nullable concept fields, which are
always present: unit_concept_id on Measurement, Observation, and
Specimen rows, unit_source_concept_id on Measurement rows, and
anatomic_site_concept_id on Specimen rows. These nullable fields are
null when the source value is absent and 0 when supplied but unmapped.
Device exposure unit_concept_id and unit_source_concept_id are always
present as null.
Each *_datetime comes from the same source as its *_date and is set
only when that source has a time of day.
Single distinct confirmed individual NPI from Practitioner.identifier or, for a role-only provider, PractitionerRole.identifier or practitioner.identifier. Recognized systems are http://hl7.org/fhir/sid/us-npi, urn:oid:2.16.840.1.113883.4.6, and 2.16.840.1.113883.4.6. Classification trims whitespace and validates ten digits and the NPI check digit; this field preserves the original value. Blank and UNK/UNKNOWN markers are missing, ignoring case and surrounding whitespace. Organization, invalid, unconfirmed, and conflicting NPIs do not populate this field.
Standard Provider concept shared by every distinct supplied role specialty; otherwise 0. Inputs resolve independently, without frequency or hierarchy selection.
Year from Practitioner.birthDate.
For recorded Practitioner.gender, male and female resolve to validated OMOP Gender concepts. other, unknown, and absent values remain 0.
The single confirmed individual NPI, including for role-only providers and when conflicting identity attributes keep an NPI group in separate rows. Check identity diagnostics and compatibility before deduplicating across responses.
Without an unambiguous individual NPI, the Practitioner's source identity is
used, excluding missing markers and unconfirmed NPIs. Role-only providers
require a confirmed NPI. Without a source identity, @provider-index:N
marks a response-local provider ordinal. Contained Practitioners use
PractitionerRole/<role-scope>#<contained-id>; a role without a source
identity uses @role-index:N as its response-local scope. These fallbacks
are not global identity guarantees; row IDs and merging are request-local.
Supplied specialty text (or coding display/code) when source values across roles agree, including unresolved text. Conflicting source values remain in provider_role_contexts and mappings.
Shared input OMOP source concept when all specialties agree on both target and source concept. Text, UMLS routes, conflicting inputs, or differing source concepts leave 0.
The recorded FHIR administrative-gender value for this Provider.
Remains 0 because FHIR administrative-gender codes do not themselves identify OMOP source concepts.
Standard OMOP Gender concept for sex at birth, from US Core birth sex when supplied, otherwise from Patient gender male or female. 0 for absent, unknown, other, unsupported, or conflicting values.
Year from Patient.birthDate.
Month from Patient.birthDate, when it supplies one.
Day from Patient.birthDate, when it supplies one.
Not set; Patient.birthDate has no time of day.
Standard OMOP Race concept from a US Core race OMB category; 1546847 (More than one race) when more than one distinct race resolves, with each race in an observation row. 0 when no category resolves.
Standard OMOP Ethnicity concept from the US Core ethnicity OMB category. 0 when absent, unresolved, or conflicting; never derived from race.
Patient.id, or the first non-empty Patient.identifier.value when id is absent. Omitted when neither is available.
The selected sex-at-birth source code: the US Core birth sex valueCode, or Patient gender when no birth sex is supplied. Conflicting birth sex values are joined with |; empty when the birth sex has no valueCode.
OMOP source concept of the selected sex-at-birth code, when that code is itself an OMOP source concept; 0 otherwise, as for FHIR administrative gender codes.
Every supplied US Core race category and detailed code, joined with | in source order, or the extension text when no code is supplied.
OMOP source concept of a single resolved race code, when that code is itself an OMOP source concept; 0 otherwise, including when more than one race resolves.
Every supplied US Core ethnicity category and detailed code, joined with | in source order, or the extension text when no code is supplied.
OMOP source concept of the resolved ethnicity code, when that code is itself an OMOP source concept; 0 otherwise.
Date from Patient.deceasedDateTime; unset for a boolean-only or partial value.
Earliest date selected by the source timing rules from the person's visit and clinical rows not listed in rows_for_review, plus Specimen and Death rows in this request. No period row is returned without qualifying dates; not enrollment evidence.
Latest date selected by the source timing rules from the person's visit and clinical rows not listed in rows_for_review, plus Specimen and Death rows in this request. Includes source end dates from unindexed rows even when the output table has no end column. No period row is returned without qualifying dates; not enrollment evidence.
Date from Encounter.period.start.
Date from Encounter.period.end.
OMOP source concept for the selected Encounter.class or Encounter.type coding when available; 0 when the source coding has no OMOP source concept, including the HL7 encounter class codes listed above.
Date from Encounter.period.start.
Date from Encounter.period.end.
OMOP source concept for the selected Encounter.class or Encounter.type coding when available; 0 when the source coding has no OMOP source concept, including the HL7 encounter class codes listed above.
The emitted same-patient overarching visit referenced by this component.
Start date selected by the source resource's timing rules. For a Condition, onsetDateTime or onsetPeriod.start, otherwise recordedDate; see the endpoint's timing sources for other resources.
End date selected by the source resource's timing rules, when available. For a Condition, abatementDateTime or abatementPeriod.end; see the endpoint's timing sources for other resources.
Explicit same-patient component link, supplied together with its overarching visit_occurrence_id.
Start date selected by the source resource's timing rules, such as effective[x], occurrenceDateTime, MedicationRequest.authoredOn, or MedicationDispense.whenHandedOver; see the endpoint's timing sources for all supported resources.
End date selected by the source resource's timing rules, when available. For medication resources, an explicit effectivePeriod.end or the start date of a single-event administration or immunization; see the endpoint's timing sources for other resources.
Date from an explicit FHIR Period.end only; inferred same-day ends are not verbatim source values.
MedicationDispense uses 32825 (EHR dispensing record); MedicationRequest uses 32838 (EHR prescription). Other current resources use 32817 (EHR). These identify record provenance, not proof of medication consumption.
Direct MedicationRequest.dispenseRequest.numberOfRepeatsAllowed value, when supplied.
Direct positive whole-day MedicationRequest.dispenseRequest.expectedSupplyDuration or coded UCUM-day MedicationDispense.daysSupply; never derived from drug quantity, dosage, refills, or timing. Does not derive an exposure end date.
Formulation-specific quantity from a direct MedicationRequest dispense quantity, MedicationDispense quantity, MedicationAdministration dose, or Immunization dose quantity. Under fixed_dose_form_count this is a matched coded tablet/capsule count copied directly, or an ingredient amount divided by per-unit strength. Under clinical_injection_ingredient_amount this is the ingredient amount, converted to the ingredient unit or derived using explicit concentration evidence; exact-unit ingredient amounts are copied directly. See the endpoint's supported dose forms and prerequisites; quantity_transformations identifies the policy, source, calculation evidence, intermediate UCUM conversion, and output unit, or explains why a supplied quantity was omitted.
Newline-joined non-empty FHIR Dosage.text instructions in source order.
Target-valid OMOP Route concept for an unambiguous coded FHIR route; 0 for an unmapped coded route, omitted for absent, text-only, or conflicting routes.
Direct FHIR R4 Immunization.lotNumber value.
Explicit same-patient component link, supplied together with its overarching visit_occurrence_id.
Selected source coding or text for an unambiguous FHIR route.
Start date selected by the source resource's timing rules. For a Procedure, performedDateTime or performedPeriod.start; see the endpoint's timing sources for other resources.
End date selected by the source resource's timing rules, when available. For a Procedure, performedPeriod.end; see the endpoint's timing sources for other resources.
Explicit same-patient component link, supplied together with its overarching visit_occurrence_id.
Start date selected by the source resource's timing rules. For an Observation, effectiveDateTime, effectivePeriod.start, or effectiveInstant; see the endpoint's timing sources for other resources.
OMOP "Meas Value Operator" standard concept qualifying value_as_number (<, <=, >, >=), parsed from a numeric-string value or a FHIR valueQuantity.comparator. 0 when no operator (a bare number).
Valid standard Unit concept for coded UCUM; 0 for supplied but unmapped units, null for absent units. Always present in JSON.
Explicit same-patient component link, supplied together with its overarching visit_occurrence_id.
OMOP source concept ID corresponding to Quantity.system/code; 0 for supplied units without a matching source concept, null for absent units. Always present in JSON.
Original Quantity.code if supplied, otherwise Quantity.unit; human-readable unit text is preserved in the unit mapping's source_name.
Request-local exposure identity, distinct from physical or model device identity.
Emitted Patient identity.
Validated standard Device concept; 0 for missing or unresolved type evidence.
Source use start at day precision; absent when unknown or unusable.
Source local wall-clock start, without UTC offset; absent for date-only input.
Explicit source end; absent when unknown or unusable.
Source local wall-clock end, without UTC offset; absent for date-only input.
Coarse source provenance; DeviceUseStatement uses generic EHR 32817.
Unambiguous supplied UDI-DI; competing values remain in source context.
Unset; supplied production components and carriers remain in source context.
Default 1 when quantity evidence is absent; otherwise omitted. See device_exposure_contexts.quantity_basis.
Compatible explicit performer on routed rows; absent for DeviceUseStatement and reporting-only actors.
Explicit emitted same-patient visit for routed rows; absent for DeviceUseStatement.
Explicit same-patient component for routed rows, with its overarching visit_occurrence_id; absent for DeviceUseStatement.
Original selected type or clinical code, or supplied text; never a resource/inventory identifier.
Original source concept when established by vocabulary resolution; otherwise 0.
Always null.
Unset; unsupported clinical units remain in source context.
Always null.
Request-local generated row identity; distinct from specimen_source_id.
Explicitly resolved top-level Patient in this response.
Material validated against Specimen; 0 for supplied unmapped material or absent material. Absence has a linked type diagnostic and no mapping/summary count; supplied unmapped material has a vocabulary mapping outcome.
32817 (EHR record provenance), independent of material and availability.
Collection date from collectedDateTime or collectedPeriod.start at day precision. Missing, partial, invalid, or conflicting timing leaves it absent with a linked diagnostic; callers must handle required-date completion for CDM loading.
Collection local wall-clock time, only when supplied; no fabricated time or offset conversion.
Exact nonnegative collection.quantity.value, without comparator or numeric conversion.
Valid standard Unit concept for coded UCUM; 0 for supplied unmapped units, null for absence.
Valid standard Spec Anatomic Site concept for a coded site; 0 for a supplied unmapped or text-only site, null for absence. Text-only sites retain source text without a concept suggestion.
Resource id, first valued identifier, accession value, then fullUrl. All source identities and selection path are in specimen_source_contexts. Kept verbatim; downstream loaders must handle CDM varchar(50) limits.
Selected bare material code or source text.
Exact Quantity.code when supplied, otherwise Quantity.unit.
Selected bare bodySite code or source text.
Start date selected by the source resource's timing rules. For an Observation, effectiveDateTime, effectivePeriod.start, or effectiveInstant. For an AllergyIntolerance, recordedDate, otherwise onsetDateTime or onsetPeriod.start; see the endpoint's timing sources for other resources.
Valid standard Unit concept for coded UCUM; 0 for supplied but unmapped units, null for absent units. Always present in JSON.
Explicit same-patient component link, supplied together with its overarching visit_occurrence_id.
For coded AllergyIntolerance rows, the known OMOP identity of the original coding rendered in observation_source_value, even when the finding is unresolved. 0 when no original source identity is known; the configured contextual finding is not a source concept.
Original Quantity.code if supplied, otherwise Quantity.unit; human-readable unit text is preserved in the unit mapping's source_name.
Compatibility assessments for explicit Encounter components, linked to the final detail or standalone visit. Omitted when no component is assessed; assessments do not contribute to terminology counts in summary.
Source child Encounter ID, when supplied.
Source child Bundle entry fullUrl, when supplied.
Supplied Encounter.partOf.reference, preserved even when grouping is not applied.
Request-local ID of the emitted child row within omop_table.
Compatibility of the selected parent/detail Visit concepts under the CDM same-concept/descendant convention. Compatible concepts must be active and standard in the Visit domain. An assessment describes classification compatibility, not the clinical truth of the source partOf relationship.
Selected parent Visit concept assessed; 0 means unresolved.
Selected candidate detail concept assessed; 0 means unresolved.
COMPATIBLEINCOMPATIBLEUNKNOWNSAME_CONCEPT and DESCENDANT are compatible outcomes. NOT_DESCENDANT means the usable concepts lack the required parent-ancestor/detail-descendant relationship. Other reasons are unknown outcomes: an unresolved or unusable concept, or insufficient ancestry evidence. Assessment unavailability or malformed results fail the request with HTTP 500 rather than returning an UNKNOWN result.
SAME_CONCEPTDESCENDANTNOT_DESCENDANTUNRESOLVED_CONCEPTCONCEPT_NOT_FOUNDINACTIVE_CONCEPTNONSTANDARD_CONCEPTWRONG_DOMAINANCESTRY_UNAVAILABLEIdentifies the unusable concept for UNKNOWN concept-validation outcomes. Absent for ANCESTRY_UNAVAILABLE and compatible/incompatible outcomes.
parentdetailPresent only for compatible outcomes; 0 for identity, positive for a descendant relationship.
Concrete vocabulary version used for both selected concepts and this assessment; matches the response vocab_version.
Audits supplied direct quantities on emitted drug_exposure rows, including derivations and omissions. Omitted when no applicable quantity was supplied. Uses the response vocabulary release and does not affect terminology counts in summary. Example concept IDs are illustrative.
MedicationRequestMedicationDispenseMedicationAdministrationImmunizationSource FHIR resource id; empty when none was supplied.
Exact source element path relative to resource_type.
dispenseRequest.quantityquantitydosage.dosedoseQuantityOriginal supplied Quantity object, including value, system, code, unit, comparator, and other supplied fields. Explicit nulls and malformed values are also preserved as supplied.
drug_exposurequantityThe drug_exposure_id of the row in this response.
DIRECT copies a matched fixed-form count or an ingredient amount in the same unit; DERIVED converts units or calculates a dose-form count or ingredient amount under the named policy; OMITTED leaves quantity unset while retaining the row.
DIRECTDERIVEDOMITTEDThe formulation policy documented in the endpoint description. May be present for an omission occurring after policy selection.
fixed_dose_form_countclinical_injection_ingredient_amountStable omission reason:
- unsupported_quantity: supplied value is not a Quantity object with a positive finite numeric value.
- unsupported_comparator: a comparator field was supplied.
- unsupported_unit: source system/code does not identify a UCUM-coded quantity or a supported HL7 TAB/CAP count.
- drug_unresolved: no standard drug concept was resolved.
- missing_drug_evidence: formulation and strength evidence is unavailable.
- incomplete_drug_evidence: required vocabulary evidence is missing or invalid.
- ambiguous_drug_evidence: more than one dose form exists, or more than one strength exists for a conversion requiring strength. Direct counts allow combination products.
- missing_classification: the selected drug's concept class is unavailable.
- unsupported_drug_class: the drug is outside Clinical Drug or Branded Drug, including quantified products and packs.
- unsupported_dose_form: the dose form has no supported classification for these policies.
- unsupported_strength: strength does not establish the selected policy, including missing, non-positive, non-finite, or conflicting values or an absent/unsupported denominator basis for volume conversion.
- unit_mismatch: the source neither matches a validated vocabulary-backed strength unit nor converts within the documented supported unit groups, or an explicit count disagrees with the selected tablet/capsule form.
- unsupported_fraction: a fixed-form count is not whole units or multiples of one-half or one-third.
- invalid_result: arithmetic does not produce a positive finite result.
unsupported_quantityunsupported_comparatorunsupported_unitdrug_unresolvedmissing_drug_evidenceincomplete_drug_evidenceambiguous_drug_evidencemissing_classificationunsupported_drug_classunsupported_dose_formunsupported_strengthunit_mismatchunsupported_fractioninvalid_resultAvailable selected-drug, dose-form, and single-ingredient strength evidence. Missing or ambiguous evidence is not replaced with an arbitrary value. On successful outcomes these fields explain the named policy's calculation.
Vocabulary concept identifying the measurement unit. For fixed_dose_form_count results this is the RxNorm dose form being counted; for clinical_injection_ingredient_amount results it is the UCUM ingredient unit. Strength units use UCUM. Codes are vocabulary-native and concept IDs belong to vocab_version.
Single-ingredient strength evidence: amount is ingredient per fixed unit; numerator/denominator describe concentration. Missing raw values remain absent without defaults. denominator_basis records the interpretation of the denominator. Box-size/refill arithmetic is not applied.
Successful case-sensitive UCUM conversion of the source magnitude into a supported strength unit. Present only when the unit code changes. The result is an intermediate value, not the linked row's quantity, and can remain present when a later policy check omits that quantity.
Original UCUM code from source_quantity.code.
Original source magnitude converted to result_unit, before strength arithmetic.
Vocabulary concept identifying the measurement unit. For fixed_dose_form_count results this is the RxNorm dose form being counted; for clinical_injection_ingredient_amount results it is the UCUM ingredient unit. Strength units use UCUM. Codes are vocabulary-native and concept IDs belong to vocab_version.
Same numeric value as the linked row's quantity.
Vocabulary concept identifying the measurement unit. For fixed_dose_form_count results this is the RxNorm dose form being counted; for clinical_injection_ingredient_amount results it is the UCUM ingredient unit. Strength units use UCUM. Codes are vocabulary-native and concept IDs belong to vocab_version.
Index of clinical rows with uncertain source status and/or primary concept 0, following the endpoint's eligibility policy. Each entry identifies an existing row in tables; payloads are not moved or duplicated. Omitted when empty. Unresolved secondary units, routes, result values, or alternate codings alone do not index a mapped row. Administrative/demographic, Specimen, and Death rows are not indexed.
Consumers select or filter the linked table rows. If a selected row points to a visit or detail marked for exclusion, either keep that target or clear the row's optional visit_occurrence_id / visit_detail_id links in the load copy. Each included detail requires its parent visit; keep that parent or exclude the detail. Returned observation periods exclude indexed dates; recompute them for a selected load if needed. Indexed rows may still lack CDM-required fields.
Original Bundle entry fullUrl, when supplied.
Supplied status, verificationStatus, and clinicalStatus fields copied verbatim from FHIR, including nulls or unreadable JSON values. Missing fields have no key. No inferred status is supplied.
Source-coding and text outcomes linked to emitted rows. Primary concepts, coded routes/results, supplied Quantity units, and specimen sites have separate entries; absent units/sites have none. Text-only sites and units can have unmapped outcomes without vocabulary resolution.
Values or routes retained outside a compatible destination column omit omop_field and have selected: false. Demographic entries link to their Person field or emitted race Observation. See MappingEntry for selection and provenance semantics, and Summary for field-level counting.
The id of the OMOP row this coding produced (e.g. condition_occurrence_id),
within omop_table. A resource with multiple codings yields one entry
per coding, all sharing this id.
The OMOP concept-ID field populated from this source coding, such as condition_concept_id, route_concept_id, or race_concept_id. Omitted when the entry preserves source information without populating a row column.
Zero-based index of this coding in its originating specialty entry's coding array. When specialty audit is available, it also identifies the corresponding resolution.specialty_resolution.coding_results outcome. Present only for coded specialty mappings, including empty Coding objects; these mappings retain the supplied coding order.
The standard concept's own code: the source code itself for an ALREADY_STANDARD row, the standard concept's code for a MAPPED row, or the suggested code for an UNCHECKED row. Omitted for UNMAPPED rows.
ALREADY_STANDARD: the source coding is already an OMOP standard concept. MAPPED: coding or descriptive text resolved to a standard concept. UNCHECKED: a suggestion is unvalidated and concept ID remains 0. UNMAPPED: no valid target was selected, or information was retained without resolution as explained in note.
Specialty entries report the selected field-level outcome; independent coding support remains in resolution.specialty_resolution.coding_results.
ALREADY_STANDARDMAPPEDUNCHECKEDUNMAPPEDWhether this coding supplies the row's source value; always present. False for alternate codings, text-only rows, specialties, and entries without a corresponding column. For demographics, marks the code determining the Person field or race Observation, even without a resolved concept. Race/ethnicity null flavors, conflicting inputs, overridden Patient gender, and race categories not determining the field are unselected.
Field-level outcome and provenance shared by that field's coding entries. Paths describe the selected concept, not independent mappings of alternates. Present for semantic attempts; omitted for source information retained without resolution, including text-only sites, units lacking supported coding, and result values retained without a corresponding row column. Allergy evidence can retain source targets that were not selected as substance values.
Semantic-mapping outcome for a supported concept field; present when inference was attempted. The containing MappingEntry supplies row/field links. Multiple coding entries can share one field outcome; group by omop_table, omop_id, and omop_field when processing it. Original source coding is preserved; text-only inputs do not invent coding.
Optional fallback decision and independent coding outcomes for one specialty entry. The enclosing resolution describes the selected result; unsupported codings can coexist with successful explicit-text resolution. Omitted when audit evidence is unavailable; omission does not change the field outcome.
Explicit source text used to select a specialty concept. Its vocabulary spelling or full preferred term is retained separately in paths[].matched_text.
Vocabulary resolution outcome. Any outcome other than RESOLVED yields mapping_status UNMAPPED and concept ID 0 while retaining an otherwise usable row.
RESOLVEDUNRESOLVEDDOMAIN_MISMATCHAMBIGUOUSMachine-readable explanation for an unresolved mapping, when available:
NO_SOURCE_CODE: no source coding was supplied.NO_OMOP_SOURCE_CONCEPT: no OMOP source concept matches the supplied coding.NO_STANDARD_MAP: no usable standard OMOP mapping was found for the supplied coding.AMBIGUOUS: multiple candidate concepts could not be disambiguated.DOMAIN_MISMATCH: candidate standard concepts do not match the domain required by the linked OMOP field.UNSUPPORTED_SYSTEM: the source code system is unsupported.UNSUPPORTED_CODE: the source code is unsupported for the linked OMOP field.CONFLICTING_ALLERGY_EVIDENCE: allergy source meanings or context conflict.UNSUPPORTED_ALLERGY_SOURCE: no supported allergy source meaning was established.UNSUPPORTED_ALLERGY_CONTEXT: the source context has no supported finding policy.UNSUPPORTED_SOURCE_MEANING: a known source concept has no supported allergy interpretation.
Unknown reason codes are omitted; status still records the outcome.
NO_SOURCE_CODENO_OMOP_SOURCE_CONCEPTNO_STANDARD_MAPAMBIGUOUSDOMAIN_MISMATCHUNSUPPORTED_SYSTEMUNSUPPORTED_CODECONFLICTING_ALLERGY_EVIDENCEUNSUPPORTED_ALLERGY_SOURCEUNSUPPORTED_ALLERGY_CONTEXTUNSUPPORTED_SOURCE_MEANINGHow the selected concept was reached: DIRECT uses vocabulary identity or Maps to; UMLS_BRIDGE uses a shared UMLS concept; CONTEXTUAL uses allergy source context. Specialty text routes identify a concept name (CONCEPT_NAME), English synonym (CONCEPT_SYNONYM), English UMLS string (UMLS_STRING), or NUCC preferred label (NUCC_LABEL). Omitted when unavailable or no concept was selected; paths retain matching evidence.
DIRECTUMLS_BRIDGECONTEXTUALCONCEPT_NAMECONCEPT_SYNONYMUMLS_STRINGNUCC_LABELMapping paths to the selected concept, in response order. Omitted when unavailable or no concept was selected.
Present and true when candidate matches were truncated during resolution. Absence means no truncation was reported.
Contextual finding policy and original coding interpretation, shared by the field's mappings. When domain-based placement supplies a result outside contextual coverage, this object retains the contextual no-match while the enclosing resolution describes placement. Missing mechanism, certainty, or activity is not inferred from source statuses. incomplete describes source-interpretation coverage; inspect finding and substance mappings independently for resolution.
Explanatory context for source interpretation, table placement, unmapped outcomes, and values retained without a corresponding row column. Demographic notes identify the source and why a supplied value was not used. Notes are human-readable text, not stable identifiers; use selected, mapping_status, and resolution fields for programmatic decisions.
One context per source record producing device exposures, with links to all derived rows and their shared timing, device evidence, and quantity basis. Preserved source values may contain clinical data.
Links to all device exposure rows derived from this source record.
Request-local ID of a row in tables.device_exposure.
Zero-based index in this context's supplied timingTiming.event evidence, including unusable events retained as partial rows. Omitted for other timing forms.
Applies to every linked exposure. default_absent_count identifies the default quantity of 1. unsupported_supplied_evidence identifies omitted quantity due to supplied clinical quantity evidence, including null or malformed numeric fields. UNSUPPORTED diagnostics identify the source paths.
default_absent_countunsupported_supplied_evidenceOriginal supplied source values with source paths. Device detail paths begin with device.; other paths refer to the clinical source resource. Timing precision, offsets, schedules, statuses, relationships, UDI carriers, and unsupported quantities are preserved here.
Original supplied JSON value, including null or malformed source evidence.
Identity, availability, and collection timing for emitted specimens, linked by specimen_id. Retains original timing precision/offsets and source identifiers; source_id_path identifies the selected specimen source ID.
Original FHIR Specimen.status for this emitted row, describing sample availability or suitability. Omitted when no status was supplied; no availability is inferred. This is source metadata, not an OMOP disease-status concept.
availableunavailableunsatisfactorySelected source path (id, identifier[index].value, accessionIdentifier.value, or fullUrl); absent if no source identity was supplied.
Supplied FHIR timing retained verbatim for audit and downstream completion. This is response provenance, not a CDM table or an inferred collection date.
Original collection.collectedDateTime, including partial precision, invalid text, or timezone offset.
Original receivedTime, never substituted for collection timing.
collection.collectedDateTime or collection.collectedPeriod.start when specimen_date was populated; omitted when no date could safely be selected.
Supplied dispensing context linked to each emitted dispense's actual output table and row. Omitted when no dispense is emitted. This provenance does not establish administration or adherence.
Original MedicationDispense.id, when supplied.
Original Bundle entry fullUrl, when supplied.
drug_exposurecondition_occurrenceprocedure_occurrencedevice_exposuremeasurementobservationOnly supplied fields are present, using original FHIR names and values: status, statusReasonCodeableConcept, statusReasonReference, category, type, whenPrepared, whenHandedOver, daysSupply, performer, context, authorizingPrescription, dosageInstruction, and medicationReference. Raw values preserve original precision, offsets, explicit nulls, and malformed values. Presence is not a promise that a value was mapped; diagnostics explain unusable values and mappings describe coded outcomes. Direct quantities are audited separately in quantity_transformations for drug_exposure rows.
Source context for every PractitionerRole linked to an emitted provider. Preserves role-specific facts that the provider's singular specialty and care-site columns cannot represent together.
The PractitionerRole source identity: its FHIR id, identifier value,
name, or fullUrl. When none is available, it is PractitionerRole.
The role's supplied practitioner reference, when present.
The logical identifier supplied on a PractitionerRole's practitioner reference. Preserves unknown NPI markers even though they are ignored for identity matching.
Every organization, healthcareService, or location reference supplied by the role.
The FHIR element path on the PractitionerRole.
Supported resources that cannot produce a row because of clinical eligibility or unusable patient, code/text, or medication evidence. Provider organizations and roles without a confirmed individual NPI or usable Practitioner are also reported. Unsupported resource types are ignored. Missing dates or other CDM-required fields usually retain partial rows; see resource-specific policies for required evidence.
Eligibility exclusions use stable resource-specific reason codes; other shaping failures use explanatory reason text.
Explains missing or unusable source data, unresolved links, and conflicting or unsupported values. When an affected row is emitted, omop_table and omop_id identify it; otherwise both are omitted. Shared issues may link to several rows. Diagnostics can accompany retained rows or dropped resources.
outcome classifies the issue, path identifies the source field, and reason provides context. Missing optional references do not produce diagnostics. References resolve only against resources supplied in this request. An invalid or unconfirmed NPI omitted from a retained Practitioner has an UNRESOLVED diagnostic at identifier.
Table containing the affected row in this response. Present together with omop_id when that row is emitted.
Primary key of the affected row within omop_table in this response. Present together with omop_table when that row is emitted.
Source field or diagnostic label. Demographic labels include
extension:birthsex and extension:ethnicity; provider identity labels
are name, gender, birthDate, and identifier. For Encounters,
class/type identifies class/type disagreement and type identifies
conflicting type classifications. Joint rules can use slash-separated
paths such as whenHandedOver/daysSupply.
The supplied Reference.reference value, when present.
- UNRESOLVED: required source data is missing, or a supported reference cannot resolve to a supplied resource or emitted target.
- AMBIGUOUS: a reference or identifier does not identify a unique target.
- CONFLICTING: source values or relationships disagree or require review under the mapping policy.
- UNSUPPORTED: a source form/type or relationship cannot be fully represented or assessed under the supported policy.
reason explains the effect on the row or link. An outcome alone does not imply that the resource was dropped; partial rows or grouping can be retained.
UNRESOLVEDAMBIGUOUSCONFLICTINGUNSUPPORTEDExplanation of the condition and its effect on mapping. Resource-specific
reason codes can be followed by ; and explanatory text; match these
codes as prefixes rather than whole strings. Collection timing uses
specimen_collection_date_missing, specimen_collection_date_partial,
specimen_collection_date_unusable, or specimen_collection_multiple_forms.
Dispensing timing uses medication_dispense_handover_missing,
medication_dispense_handover_partial, or medication_dispense_handover_unusable.
medication_dispense_handover_before_preparation identifies conflicting
handover/preparation timing;
medication_dispense_end_date_absent identifies an unset exposure end.
The OMOP vocabulary release used for coded concept resolution (for example, "v20260829"), for reproducibility. Omitted when no vocabulary resolution was performed.
Resolution outcome counts and the share not already standard. Each evaluated field contributes one outcome even when several codings produce mappings.
| Included outcomes | Counting unit |
|---|---|
| Primary clinical concepts, specimen material/sites, supplied Quantity units on Measurement/Observation/Specimen, coded Observation results on Measurement/Observation, allergy substance values, Encounter classifications, Address.country, CMS Place of Service, and recorded Practitioner gender | Each evaluated field |
| Coded medication/Immunization routes, including context on other destinations | Each source-selected route; report-only alternates do not add outcomes |
| Provider specialties | Each distinct input per provider |
| Patient demographics | Each selected Person field or emitted race Observation; conflicting values count once as unmapped |
Absent specimen material/sites and units do not count. Demographic null flavors, Patient gender other/unknown or overridden by birth sex, and race categories not determining a field are reported only in mappings. Observation values retained without a corresponding row column, quantity audits, and visit compatibility assessments do not add resolution outcomes. Dropped resources do not count; indexed rows remain included in codes_* and off_vocab_rate.
Resolution outcomes already a standard OMOP concept (ALREADY_STANDARD).
Resolution outcomes mapped or suggested to a standard concept (MAPPED or UNCHECKED).
Resolution outcomes with no standard concept valid for the destination selected (UNMAPPED).
Length of the rows_for_review index; each row counts once even with multiple retention reasons. codes_* and off_vocab_rate include all shaped rows; dropped resources do not count.
Share of resolution outcomes not already standard ((normalized + unmapped) / total).