Map FHIR resources to OMOP CDM v5.4

Maps a FHIR R4 resource or Bundle into OMOP Common Data Model v5.4 rows, grouped by destination table in tables.

Set vocab_version to select the OMOP vocabulary release used for coded concept resolution. If omitted or empty, the API uses its default release. The response's vocab_version, when present, identifies the release used. Specify a release explicitly when reproducibility matters.

Standards basis: FHIR R4 (v4.0.1) defines the accepted source elements and OMOP CDM v5.4 defines the output columns. The published Vulcan FHIR-to-OMOP IG v1.0.0 is an informative FHIR R5 baseline; this endpoint documents and implements the equivalent R4 source elements, rather than accepting R5-only fields.

This response is a mapping result, not a complete CDM load pipeline. When a source cannot supply a field that CDM v5.4 requires, the row is still returned with that field unset; the value is not inferred. Common cases are year_of_birth without a usable birthDate, drug_exposure_end_date without an explicit end or single-event timing, and a required event date (such as condition_start_date, procedure_date, or death_date) whose source has no timing with at least day precision. Apply your own policy to such rows before loading them into a strictly conformant CDM instance.

Current resource coverage:

• Patient -> person; deceased[x] can also produce death, the first address can produce location, and more than one supplied race produces observation race rows (see Patient demographics below)
• observation_period -> one request-local derived row per person, spanning dates from that person's visit, clinical, and death records, including source end dates even when the output table has no end column; this is not enrollment or capture-completeness evidence
• Location -> location and care_site
• Organization -> care_site; its first address can produce location
• HealthcareService -> care_site
• Practitioner and PractitionerRole -> provider
• Encounter -> visit_occurrence
• Specimen -> specimen, with an explicit Patient subject; missing collection date or material retains a partial row with diagnostics
• Condition -> domain-selected clinical table; default condition_occurrence
• Procedure -> domain-selected clinical table; default procedure_occurrence
• MedicationRequest, MedicationStatement, and MedicationAdministration -> domain-selected clinical table; default drug_exposure
• Immunization -> domain-selected clinical table; default drug_exposure
• Observation -> domain-selected clinical table. Numeric values prefer measurement and other values prefer observation when the code is valid for both tables. For text-only Observations, numeric values route to measurement and nonnumeric values to observation.
• AllergyIntolerance -> domain-selected clinical table excluding drug_exposure; default observation

Clinical placement follows the informative Vulcan IG's vocabulary-driven domain assignment. Supported destinations are condition_occurrence, procedure_occurrence, drug_exposure, measurement, and observation. Coded clinical records are returned in the table corresponding to the domain of their mapped OMOP standard concept. The source resource determines eligibility, field values, and the default table when no supported mapping is available. Allergy substance codes must not create drug exposures.

For example, a Condition coded with ICD10CM Z79.4 can produce a mapped observation row. Z86.73 and ICD-O-3 8140/3 also map to concepts in the Observation domain. Use mappings.omop_table and mappings.omop_id to locate each result; the FHIR resource type alone does not determine the output table.

Clinical rows include available person/visit/provider links, concept and source concept IDs, source value, source type provenance, and start timing. Dates follow the source resource's timing rules below, regardless of the output table. For example, a Condition follows its onset[x] / recordedDate timing rule even when returned as an observation. End dates are populated only in tables with end columns; they also contribute to the request-local observation period when the output table has no end column.

Source-specific fields are populated only for the corresponding source and destination: Condition status in condition_occurrence, medication dosage/supply and Immunization lot details in drug_exposure, and Observation values/units/ranges in measurement or observation where those columns exist. Mapping notes explain the output table and which fields are populated. Coded medication/immunization routes on rows outside drug_exposure, and Observation values on rows outside measurement / observation, are retained in mappings linked to the output row, with omop_field omitted and selected: false. Coded routes are checked against the OMOP Route domain; those Observation values are preserved without concept resolution.

Device and Note destinations are unsupported. If no standard concept valid for a supported destination is found, the resource produces a row in its default table with concept and source concept IDs of 0 and UNMAPPED status. A DOMAIN_MISMATCH outcome is identified in the mapping note. For example, a Procedure coded with HCPCS C5271 produces a partial procedure_occurrence row because its mapped domain is Device. Text-only inputs use their default tables. A resource produces one clinical row even when its code has multiple vocabulary mapping targets. Vocabulary Maps to value mappings are not applied.

Medication is reference data for medication resources; it does not create its own row because OMOP CDM has no Medication table. Administrative linkages (provider, care site, and location) are best-effort and limited to references supplied in the request. Patient.managingOrganization is a record custodian, not a care-delivery site. Provider specialty is not mapped. Recorded Practitioner.gender is distinct from Person demographics: male and female resolve to validated OMOP Gender concepts in provider.gender_concept_id; other, unknown, and absent gender remain unmapped. Address.country is resolved to location.country_concept_id, and CMS Place of Service codings in Location.type are resolved to care_site.place_of_service_concept_id. Within one request, Practitioners with the same single distinct non-empty NPI under http://hl7.org/fhir/sid/us-npi merge into one provider row only when all supplied mapped identity attributes in the entire NPI group agree. This includes Practitioners contained in valid role references. System and value matches are exact; other identifier systems and names do not trigger a merge. Missing attributes can enrich a compatible merged row. Compatibility compares the name rendered from each Practitioner's first name entry, its gender, its first non-empty DEA identifier, and its parsed birth year. Differences in birth month/day within one year do not conflict. Rendered names are compared exactly: Jane Smith and Dr. Jane Smith conflict even when they share an NPI. If any of these attributes conflict, every resource in that NPI group stays separate, including resources missing the conflicting attribute. Source attributes and unambiguous structural reference links are preserved; no conflicting value is selected. Each affected row has CONFLICTING diagnostics at name, gender, identifier, or birthDate, linked by omop_table: provider and omop_id. All source gender mappings link to their retained or merged provider row. Repeated copies of one NPI on a resource are allowed. A resource with multiple distinct NPIs stays separate, leaves npi unset, preserves its source-resource identity in provider_source_value, and reports a CONFLICTING diagnostic at identifier linked by omop_table: provider and omop_id. Row IDs are per response. The API does not merge across requests. For a Practitioner with one NPI, provider_source_value is that NPI, even when its group conflicts. Consumers can use it to deduplicate compatible providers across requests, but must preserve rows flagged by identity conflict diagnostics and check compatibility across responses. Without one unambiguous NPI, source-resource identity is preserved without a person-level deduplication guarantee. A PractitionerRole that identifies one supplied Practitioner aliases that canonical provider: by a top-level structural reference, a parent-contained #id reference, or an exact identifier.system and identifier.value match against a top-level Practitioner. No remote identifier lookup is performed. When Reference.type is present it must be Practitioner; duplicate contained IDs and identifier matches to different canonical providers are ambiguous. An explicit reference that is unresolved, ambiguous, or unsupported retains a role-fallback provider row and is returned in diagnostics. provider_role_contexts preserves role-specific specialty and care-site context that a canonical OMOP provider row cannot represent together.

Patient demographics:

• Sex at birth, race, and ethnicity are read from these US Core extensions, with their US Core 6.1.0 structures and value sets, on any Patient (US Core profile conformance is not required). Sex at birth falls back to Patient gender. Other extensions, including US Core sex and gender identity, are ignored.
  • Birth sex: http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex (valueCode from http://hl7.org/fhir/us/core/ValueSet/birthsex)
  • Race: http://hl7.org/fhir/us/core/StructureDefinition/us-core-race (ombCategory from http://hl7.org/fhir/us/core/ValueSet/omb-race-category)
  • Ethnicity: http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity (ombCategory from http://hl7.org/fhir/us/core/ValueSet/omb-ethnicity-category)
• gender_concept_id is sex at birth. A supplied birth sex always decides it: M and F are resolved; UNK, ASKU, OTH, a code outside the value set, conflicting values, and a birth sex without valueCode leave it 0, and Patient gender is not used.
• Without a birth sex, Patient gender male or female is resolved under the OMOP convention that the supplied gender represents sex at birth; other and unknown keep concept 0.
• gender_source_value is the chosen source code (F for birth sex, female for Patient gender).
• Each race category is resolved separately, and null flavors (UNK, ASKU) are ignored. One distinct standard race sets race_concept_id. More than one sets it to 1546847 (More than one race) and adds one observation row per race, with observation_concept_id 4013886 (Race), the race in value_as_concept_id, observation_type_concept_id 32817, the category code in value_source_value, and no observation_source_value or observation_date. A loading pipeline that requires observation_date must apply its own date policy.
• The single non-null ethnicity category is resolved, and null flavors are ignored; more than one distinct category leaves ethnicity_concept_id 0. Ethnicity is not derived from race, and no demographic is inferred from names, addresses, or other extensions.
• race_source_value and ethnicity_source_value list every supplied category and detailed code in source order, joined with |, or the extension text when no code is supplied. Detailed codes and text are not resolved.
• Every supplied birth sex, gender, and OMB category code has a mappings entry whose note names its source and outcome. When a birth sex is supplied, Patient gender is reported unselected with the note FHIR administrative gender; not used, birth sex supplied. Conflicting values and a birth sex without valueCode are also returned in diagnostics with path extension:birthsex or extension:ethnicity. summary counts each demographic field once, as described under Summary.
• Differences from the reference conventions: Vulcan's example gender ConceptMap maps other and unknown to concepts, which stay 0 here; more than one race follows the OHDSI THEMIS convention, also used by Vulcan, rather than the CDM 5.4 note that mixed races use 0; and Vulcan's suggested observation rows for multiple ethnicities are not produced.

Specimen produces a specimen row only with an explicitly resolvable top-level Patient subject. Missing collection dates or material retain useful partial rows with linked diagnostics; those rows may require downstream completion before loading into a strict CDM instance. References support Patient/id and exact Bundle fullUrl matches (including URNs and absolute URLs); contained, logical, display-only, missing, non-Patient, and unresolved subjects never use the sole Patient fallback. Reference.type, when supplied, must identify Patient. Unsafe patient attribution and ineligible status drop only that Specimen with dropped and diagnostics; a missing Patient in the entire request remains a 400. Missing material is concept ID 0 with a type diagnostic and no terminology mapping/summary count. Supplied unmapped material is also 0, with its separate vocabulary mapping outcome and retained source code. Material (type) resolves against the Specimen domain, coded UCUM collection quantity units against Unit, and collection.bodySite against Spec Anatomic Site. Supplied unmapped optional concepts are 0; absent unit and site IDs are explicit null. Text-only body sites preserve their source text with site concept ID 0 and an UNMAPPED mapping; they do not produce a text-based concept suggestion. Text-only material can produce an UNCHECKED suggestion with material concept ID 0. Numeric quantity is copied without unit conversion; invalid or comparator-bearing quantities are omitted with diagnostics without dropping the row. Missing optional data is allowed. Collection time uses collection.collectedDateTime or collection.collectedPeriod.start; end-only, partial, invalid, and absent dates leave specimen_date/specimen_datetime omitted with linked diagnostics. Both collected forms together are conflicting: retain the row without selecting a date. Period end and receivedTime never substitute for collection start. specimen_source_contexts.collection_timing preserves raw dateTime, Period boundaries, receivedTime, and the selected source path when a date is populated, including partial precision and original timezone offsets. specimen_collection_date_missing, specimen_collection_date_partial, and specimen_collection_date_unusable distinguish absent, partial, and invalid source dates; specimen_collection_multiple_forms reports conflicting choices. specimen_type_concept_id: 32817 is EHR provenance, independent of material and availability. Status absent/available/unavailable/unsatisfactory is supported; entered-in-error and unrecognized statuses drop the specimen. specimen_source_contexts.status preserves the supplied availability status for emitted rows; it is omitted when no status was supplied. Disease status is not inferred. Source identity precedence is resource id, then first identifier with a nonempty value in source array order, then accessionIdentifier.value, then Bundle fullUrl. No identity is fabricated; specimen_source_contexts preserves all valued identifier system/value pairs, accession identity, resource id/fullUrl, and the selected source path. Parent/derived specimens emit independently when each has its own Patient; missing date/material remains partial rather than being inherited. Parent and Measurement-to-Specimen links are not represented. Consuming CDM loaders own required-date completion, durable IDs, and dataset completeness. Source baseline is FHIR R4 4.0.1, with supported common fields reviewed against US Core Specimen 7.0.0; full profile conformance is not validated here.

DiagnosticReport, ServiceRequest, CarePlan, DocumentReference, Composition, DeviceUseStatement, Coverage, Claim, and other unsupported resource types are accepted in a Bundle but ignored: they create no row and no dropped entry. dropped is reserved for supported row-producing resources that cannot safely produce a positive OMOP row: required subject/patient, clinical code/text, or medication data may be unusable, or the resource may explicitly negate or fail the documented clinical-event eligibility policy. A single-Patient Bundle uses the sole Patient only when subject/patient is absent. An explicit subject/patient reference that is unresolved, ambiguous, or unsupported drops the clinical resource in every request scope.

Eligibility distinguishes clinical validity, performed/taken evidence, and administrative workflow state. Entered-in-error and explicitly non-performed events never produce a positive clinical-event row, and an unrecognized required status fails closed. Condition requires absent or confirmed canonical-HL7 verificationStatus; clinical course is not a diagnosis-role mapping. Procedures accept completed or stopped events. Medication requests are prescription evidence only: doNotPerform, drafts, cancellations, and non-authorizing intents are dropped. Medication statements accept active, completed, stopped, or on-hold reported use; administrations accept completed, in-progress, on-hold, or stopped events. An on-hold administration also needs an effectiveDateTime or effectivePeriod.start that supplies start evidence; a valid partial date remains an undated row. An on-hold administration is started evidence that is temporarily paused and expected to continue. Immunizations require completed status. Observations require final, amended, or corrected status; registered, preliminary, cancelled, entered-in-error, unknown, and missing statuses are dropped. AllergyIntolerance accepts absent, unconfirmed, or confirmed canonical-HL7 verificationStatus as a reported allergy, but drops refuted, entered-in-error, and unreadable supplied verification statuses. Encounter accepts arrived, triaged, in-progress, onleave, or finished status, but drops planned, cancelled, entered-in-error, unknown, and missing statuses. An eligible encounter without Period.end remains a partial visit; no end date is invented.

The mapped OMOP concept's domain determines the clinical output table. For Observations, numeric and nonnumeric value[x] forms determine the preferred table only when the code is valid for both measurement and observation. Text-only Observations produce measurement rows for numeric values and observation rows for other values. In these two tables, numeric values populate value_as_number; other non-coded values populate value_as_string for an observation or value_source_value for a measurement. Coded valueCodeableConcept values are resolved against value_as_concept_id in these tables and use the selected bare code in value_source_value, leaving an observation's value_as_string empty; unmapped or target-invalid coded values remain 0. Active standard concepts from any OMOP domain are valid for value_as_concept_id per CDM 5.4. For example, a blood-culture Measurement can record Staphylococcus aureus as its coded result, even though the organism concept belongs to OMOP's Observation domain. For other clinical output tables, Observation values are retained only in mappings, without concept resolution or an omop_field, and with selected: false. Other unsupported value[x] forms and Observation components do not populate separate converted values. A numeric comparator (<, <=, >, >=) is represented only by a measurement's operator_concept_id.

For Observations returned as measurement or observation rows, Quantity units resolve independently against the table's unit_concept_id. Other clinical output tables have no unit columns; their units are not resolved or included as separate mapping outcomes. Only coded UCUM (http://unitsofmeasure.org or its OID 2.16.840.1.113883.6.8, bare or urn:oid:) is supported. Codes are case-sensitive: no spelling aliases, text-only guesses, or numeric conversion are applied. Coded UCUM units map to valid standard OMOP Unit concepts using the release selected by vocab_version (default v20260227 when omitted or empty). Mappings are direct or follow an active OMOP Maps to relationship; UCUM units do not use a UMLS bridge. Unknown codes, vocabulary gaps, text-only units, missing coding, and unsupported systems keep the row and use 0; absent units use JSON null (the field is present). Explicit dimensionless code 1 is a supplied unit and resolves or remains 0; it is never treated as absent. unit_source_value contains Quantity.code when supplied, otherwise Quantity.unit. A separate unit mappings entry preserves the original Quantity.system/code in source_system/source_code and the exact human-readable Quantity.unit in source_name, with its own outcome. Quantity.unit provides display text and does not affect unit matching. Measurement also returns nullable unit_source_concept_id, identifying the OMOP source concept for Quantity.system/code when available, otherwise 0 for a supplied unit. Observation has no such column. Resolving a unit does not change numeric values, comparators, or reference ranges. Supported coded UCUM units include resolution in their mappings, whether the unit resolves or remains unmapped: its outcome and reason code distinguish vocabulary gaps, target-domain mismatches, and ambiguity. Unresolved or ambiguous units retain the row with concept ID 0. Resolved mappings retain the selected concept's direct or crosswalk provenance. Text-only units, units with missing coding, and unsupported unit systems omit resolution; their note explains the unmapped outcome.

Compatibility: absent unit_concept_id values previously returned 0 and now return null. Coded units use their code in unit_source_value rather than their human-readable text; the text remains in mappings. The Measurement unit_source_concept_id field is new.

A standard OMOP concept_id is selected for each eligible primary clinical coding after considering all of the resource's supplied codings. An unambiguous coded medication or immunization route is checked independently against the OMOP Route domain. For drug_exposure rows, route_concept_id contains the resolved concept ID, or 0 if unmapped; for other output tables the route is reported only in mappings, without omop_field and with selected: false. Alongside the OMOP rows grouped by table (tables), the response carries mappings (an entry for every supported source coding from a resource that shaped a row, linked back to that row; some, such as demographic null flavors, are reported without being resolved), provider_role_contexts (source role details linked to provider rows), dropped (resources that could not be shaped into a row), diagnostics (explicit references that could not safely create a link, conflicting Practitioner identity attributes, conflicting or unsupported Patient demographic extensions, and conflicting Encounter classifications), vocab_version (the OMOP vocabulary release codes were resolved against), and a small summary of the resolution outcomes.

A concept_id of 0 is reported, not omitted (OMOP "no matching concept" semantics): it covers both a coding with no standard match (UNMAPPED) and an unverified suggestion for a text-only resource (UNCHECKED). Supported Encounter.class or Encounter.type values may populate visit_concept_id. Person demographics and Provider recorded gender follow the policies above. Coded Observation values may populate value_as_concept_id. Measurement operator_concept_id represents a value comparator (<, <=, >, >=); multiple-race concepts follow the conventions described above. Clinical *_source_value fields contain the selected FHIR code (or source text for text-only resources). The corresponding selected mappings entry preserves the coding system and full source-coding provenance. Known OID-form coding systems are accepted as either FHIR OID URNs (for example, urn:oid:2.16.840.1.113883.6.1 for LOINC) or bare OIDs, and produce the same mappings as their canonical system URLs. Coding mappings report that canonical URL in source_system; Quantity unit mappings preserve the original Quantity.system, including OID spelling. An unknown OID remains unchanged in source_system and may be UNMAPPED. Other *_source_value fields preserve row-specific raw source values, such as resource identifiers, names, units, or status codes. MedicationRequest uses 32838 (EHR prescription) for drug_type_concept_id; other current resources use 32817 (EHR). This is a coarse provenance policy: it does not infer patient-reported, medication-history, or other more-specific type concepts from FHIR status fields.

Dates and datetimes:

• A *_date is the calendar date (YYYY-MM-DD) of a source value with at least day precision. A *_datetime is set only when that value has a time of day, as local time without a UTC offset (YYYY-MM-DDTHH:MM:SS, with fractional seconds to microseconds when supplied): 2024-01-15T23:30:00-05:00 becomes 2024-01-15T23:30:00. A datetime without a timezone is read as local time.
• A partial date (2024 or 2024-03) leaves both columns unset. It still counts as that source's value, so later sources in the list below are not used.
• Free-text timing (such as onsetString), Age and Range forms, and values that are not dates are ignored, so a later source in the list is used if there is one.
• Other than the sources below and the same-day ends of single-event medication records, no date is imputed: partial dates are not completed, and a row is not dated from another resource such as its Encounter.
• Valid date values never cause a request to be rejected, and the response reports unusable date elements for Specimen while retaining the partial row for downstream load completion. Other rows do not report which date elements were unusable. An on-hold MedicationAdministration is an eligibility exception: it needs a supplied effective start as evidence that administration began.

Timing sources, in priority order where several are listed. These rules apply regardless of the clinical output table; end dates are populated only where the table has an end column, and verbatim_end_date is set only for medication resources returned as drug_exposure rows:

• Patient: birthDate sets year_of_birth, month_of_birth, and day_of_birth from the parts it supplies; birth_datetime is not set. deceasedDateTime sets the death dates.
• Practitioner: birthDate sets the provider's year_of_birth.
• Encounter: period.start and period.end.
• Condition: start from onsetDateTime or onsetPeriod.start, then recordedDate (when the condition was recorded, not when it began); end from abatementDateTime or abatementPeriod.end.
• Procedure: start from performedDateTime or performedPeriod.start; end from performedPeriod.end only.
• Specimen: collection.collectedDateTime or collection.collectedPeriod.start; missing day precision retains an undated specimen with diagnostics.
• Observation: effectiveDateTime, effectivePeriod.start, or effectiveInstant.
• AllergyIntolerance: recordedDate, then onsetDateTime or onsetPeriod.start.
• MedicationStatement: start from effectiveDateTime or effectivePeriod.start; end and verbatim_end_date from effectivePeriod.end. dateAsserted records when the statement was made and is not used.
• MedicationAdministration: an effectiveDateTime is a single event that sets both start and end; an effectivePeriod sets the start and, when present, the end and verbatim_end_date.
• Immunization: occurrenceDateTime is a single event that sets both start and end; expirationDate is not used.
• MedicationRequest: authoredOn, the order date, sets the start; it is not evidence of administration. No end is set, and the validity period is not used as an exposure duration.
• Differences from the Vulcan maps: birth_datetime is not set from birthDate, Condition also reads onsetPeriod.start, and AllergyIntolerance falls back to its onset when recordedDate is missing.

Medication details for resources returned as drug_exposure rows:

• For MedicationRequest, dispenseRequest.numberOfRepeatsAllowed sets refills and a whole-day expectedSupplyDuration sets days_supply.
• All non-empty dosage text is preserved in sig.
• Coded dosage routes and Immunization.route are target-validated in the OMOP Route domain. Conflicting routes are left unset; route codings shared by every dosage instruction identify the same route.
• Immunization.lotNumber is preserved in lot_number.

Encounter details:

• Encounter classifications must supply both Coding.system and Coding.code to map to a standard OMOP Visit concept. For HL7 encounter class codes with system http://terminology.hl7.org/CodeSystem/v3-ActCode or http://hl7.org/fhir/v3/ActCode, the supported mappings are:

  • IMP (inpatient encounter) -> 9201 (Inpatient Visit)
  • AMB (ambulatory encounter) -> 9202 (Outpatient Visit)
  • EMER (emergency encounter) -> 9203 (Emergency Room Visit)
  • VR (virtual encounter) -> 722455 (Telehealth)
  • HH (home health encounter) -> 581476 (Home Visit)

  OBSENC (observation encounter) has no direct class mapping. Other class or type codes can be used when they have a valid standard OMOP Visit mapping in the selected vocabulary release. Unsupported classifications retain visit_concept_id of 0 unless a supported type supplies the Visit as described below; they never default to outpatient.

• A mapped Encounter.class determines visit_concept_id. A mapped type that disagrees with it produces a CONFLICTING diagnostic with path class/type, while the class mapping remains selected. If class is missing or unmapped, type supplies the Visit only when all mapped type classifications agree on the same standard Visit concept. Codings within one type CodeableConcept are alternative encodings of that classification. When separate type classifications map to different Visit concepts, no type is selected, visit_concept_id remains 0, and a CONFLICTING diagnostic has path type.

• visit_source_value contains the selected class or type code; mappings preserves its coding system and identifies which classification was selected. visit_source_concept_id identifies the selected original source coding's OMOP concept when available, and is 0 otherwise, including for the HL7 encounter class codes listed above. Each eligible Encounter produces one Visit; classHistory, partOf, and admission/discharge concepts are not mapped.

Medication codes are resolved whether they appear inline (medicationCodeableConcept) or via a medicationReference to a contained, relative (Type/id), or bundle-entry (urn:uuid) Medication resource. A reference that resolves to another resource type is dropped even when it supplies display text; an unresolved or display-only reference may use its display as text-only medication input. Resources that cannot be shaped into a row — a medication with no usable code, resolvable reference, or display; any clinical resource whose subject/patient reference cannot be tied to a person; or an event excluded by eligibility — are reported under dropped rather than emitted as blank rows. The Bundle must contain at least one Patient resource.

Structural references resolve only to top-level resources supplied in the request, by Type/id or an exactly matching Bundle fullUrl (including urn:uuid). Contained references are supported for medication code lookup and PractitionerRole.practitioner enrichment; the latter also supports exact request-local identifier matching without a remote lookup. Every nonzero structural foreign key targets a row in the same response. Missing optional links remain unset without a diagnostic; an explicit optional reference that is unresolved, ambiguous, conflicting with the row's person, or unsupported remains unset and is returned in diagnostics with its source path and outcome.

All row IDs start at 1 for each request and are not stable or global. For clinical conversion rows whose resource supplies an id, mappings associates each row with that source FHIR resource ID. A person row retains the Patient ID or its first identifier value in person_source_value, when present; other reference and derived rows do not uniformly carry a FHIR resource ID. Input resources without those source identifiers cannot be correlated across responses from the returned rows alone. Consumers combining responses need to establish their own stable keys and remap every primary and foreign key together.