From d51dfbf4cb4ce03235262af481cd5a7e42d8452b Mon Sep 17 00:00:00 2001 From: glebmark <87950237+glebmark@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:16:08 +0400 Subject: [PATCH 1/2] [HealthSamurai/smartbox#588] fixes after review --- SUMMARY.md | 2 +- docs/data-integration/README.md | 2 +- docs/data-integration/uscdi/README.md | 48 +++++++++---------- docs/data-integration/uscdi/allergies.md | 3 +- docs/data-integration/uscdi/conditions.md | 2 +- docs/data-integration/uscdi/devices.md | 2 +- docs/data-integration/uscdi/encounters.md | 2 +- docs/data-integration/uscdi/goals.md | 4 +- docs/data-integration/uscdi/immunizations.md | 2 +- .../uscdi/patient-demographics.md | 12 ++++- docs/data-integration/uscdi/procedures.md | 2 +- 11 files changed, 44 insertions(+), 37 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index d91a837..e073959 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -70,7 +70,7 @@ * [Problems](data-integration/uscdi/conditions.md) * [Immunizations](data-integration/uscdi/immunizations.md) * [Goals](data-integration/uscdi/goals.md) - * [Unique Device Identifiers](data-integration/uscdi/devices.md) + * [Device](data-integration/uscdi/devices.md) * [Encounter Information](data-integration/uscdi/encounters.md) * [Procedures](data-integration/uscdi/procedures.md) * [Assessment and Plan of Treatment](data-integration/uscdi/care-plans.md) diff --git a/docs/data-integration/README.md b/docs/data-integration/README.md index 47e3b61..7c5d610 100644 --- a/docs/data-integration/README.md +++ b/docs/data-integration/README.md @@ -20,7 +20,7 @@ graph LR | Rule | Detail | |---|---| -| Format | Agreed per engagement. If you deliver CSV: UTF-8, comma-delimited, RFC 4180 quoting, first row is the headers, named exactly as in the tables. | +| Format | Agreed per engagement. If you deliver CSV: UTF-8, comma-delimited, first row is the headers, named exactly as in the tables. | | Delivery | Arranged per engagement. PHI: encrypted in transit and at rest under the executed BAA. | | History (USCDI feed) | Date of service on or after January 1, 2016. Send active and historical records; the status columns mark which is which. | diff --git a/docs/data-integration/uscdi/README.md b/docs/data-integration/uscdi/README.md index e405b37..b8fd019 100644 --- a/docs/data-integration/uscdi/README.md +++ b/docs/data-integration/uscdi/README.md @@ -8,27 +8,27 @@ description: >- | # | Dataset | USCDI v3.1 data class | US Core 6.1.0 target profile(s) | |---|---|---|---| -| 1 | [`patients`](patient-demographics.md#patients) | [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3) | [US Core Patient](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html) (+ race, ethnicity, sex, tribal extensions) | -| 2 | [`related_persons`](patient-demographics.md#related-persons) | [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3) | [US Core RelatedPerson](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-relatedperson.html) | -| 3 | [`practitioners`](care-team.md#practitioners) | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3) (ref), may come from [Provider Directory](../provider-directory/README.md#providers) | [US Core Practitioner](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitioner.html), [US Core PractitionerRole](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitionerrole.html) | -| 4 | `organizations` | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Organization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-organization.html) | -| 5 | [`locations`](encounters.md#locations) | [Encounter Information](https://isp.healthit.gov/taxonomy/term/2986#uscdi-v3) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Location](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-location.html) | -| 6 | [`allergies`](allergies.md#allergies) | [Allergies and Intolerances](https://isp.healthit.gov/taxonomy/term/2941#uscdi-v3) | [US Core AllergyIntolerance](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-allergyintolerance.html) | -| 7 | [`conditions`](conditions.md#conditions) | [Problems](https://isp.healthit.gov/taxonomy/term/3066#uscdi-v3) | [US Core Condition Problems and Health Concerns](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-problems-health-concerns.html), [US Core Condition Encounter Diagnosis](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-encounter-diagnosis.html) | -| 8 | `medications` | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3) | [US Core MedicationRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationrequest.html), [US Core Medication](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medication.html) | -| 9 | `medication_dispenses` | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3) (Fill Status) | [US Core MedicationDispense](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationdispense.html) | -| 10 | [`immunizations`](immunizations.md#immunizations) | [Immunizations](https://isp.healthit.gov/taxonomy/term/3021#uscdi-v3) | [US Core Immunization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-immunization.html) | -| 11 | [`procedures`](procedures.md#procedures) | [Procedures](https://isp.healthit.gov/taxonomy/term/3071#uscdi-v3) | [US Core Procedure](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-procedure.html) | -| 12 | [`service_requests`](procedures.md#service-requests) | [Procedures](https://isp.healthit.gov/taxonomy/term/3071#uscdi-v3) (Referral, SDOH Interventions) | [US Core ServiceRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-servicerequest.html) | -| 13 | [`encounters`](encounters.md#encounters) | [Encounter Information](https://isp.healthit.gov/taxonomy/term/2986#uscdi-v3) | [US Core Encounter](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-encounter.html) | -| 14 | [`care_team`](care-team.md#care-team) | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3) | [US Core CareTeam](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careteam.html) | -| 15 | [`care_plans`](care-plans.md#care-plans) | [Assessment and Plan of Treatment](https://isp.healthit.gov/taxonomy/term/2946#uscdi-v3) | [US Core CarePlan](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careplan.html) | -| 16 | [`goals`](goals.md#goals) | [Goals](https://isp.healthit.gov/taxonomy/term/3006#uscdi-v3) | [US Core Goal](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-goal.html) | -| 17 | [`coverage`](health-insurance.md#coverage) | [Health Insurance Information](https://isp.healthit.gov/taxonomy/term/3016#uscdi-v3) | [US Core Coverage](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-coverage.html) | -| 18 | `documents` | [Clinical Notes](https://isp.healthit.gov/taxonomy/term/2961#uscdi-v3) | [US Core DocumentReference](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-documentreference.html) | -| 19 | `diagnostic_reports` | [Clinical Notes](https://isp.healthit.gov/taxonomy/term/2961#uscdi-v3), [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3), [Diagnostic Imaging](https://isp.healthit.gov/taxonomy/term/2971#uscdi-v3) | [US Core DiagnosticReport Lab](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-lab.html), [US Core DiagnosticReport Note](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-note.html) | -| 20 | [`devices`](devices.md#devices) | [Unique Device Identifier(s)](https://isp.healthit.gov/taxonomy/term/3126#uscdi-v3) | [US Core Implantable Device](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-implantable-device.html) | -| 21 | `vital_signs` | [Vital Signs](https://isp.healthit.gov/taxonomy/term/3131#uscdi-v3) | [US Core Vital Signs](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-vital-signs.html) | -| 22 | `labs` | [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3) | [US Core Laboratory Result Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-lab.html), [US Core Specimen](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-specimen.html) | -| 23 | [`social_history`](patient-demographics.md#social-history) | [Health Status Assessments](https://isp.healthit.gov/taxonomy/term/4401#uscdi-v3), [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3) (Occupation) | [US Core Smoking Status](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-smokingstatus.html), [US Core Observation Occupation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-occupation.html), [US Core Observation Pregnancy Status](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-pregnancystatus.html) | -| 24 | `clinical_observations` | [Clinical Tests](https://isp.healthit.gov/taxonomy/term/2976#uscdi-v3), [Diagnostic Imaging](https://isp.healthit.gov/taxonomy/term/2971#uscdi-v3), [Health Status Assessments](https://isp.healthit.gov/taxonomy/term/4401#uscdi-v3) | [US Core Observation Clinical Result](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-clinical-result.html), [US Core Observation Screening Assessment](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-screening-assessment.html), [US Core Simple Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-simple-observation.html) | +| 1 | [`patients`](patient-demographics.md#patients) | [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3-1) | [US Core Patient](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html) (+ race, ethnicity, sex, tribal extensions) | +| 2 | [`related_persons`](patient-demographics.md#related-persons) | [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3-1) | [US Core RelatedPerson](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-relatedperson.html) | +| 3 | [`practitioners`](care-team.md#practitioners) | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#providers) | [US Core Practitioner](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitioner.html), [US Core PractitionerRole](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitionerrole.html) | +| 4 | `organizations` | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Organization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-organization.html) | +| 5 | [`locations`](encounters.md#locations) | [Encounter Information](https://isp.healthit.gov/taxonomy/term/2986#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Location](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-location.html) | +| 6 | [`allergies`](allergies.md#allergies) | [Allergies and Intolerances](https://isp.healthit.gov/taxonomy/term/2941#uscdi-v3-1) | [US Core AllergyIntolerance](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-allergyintolerance.html) | +| 7 | [`conditions`](conditions.md#conditions) | [Problems](https://isp.healthit.gov/taxonomy/term/3066#uscdi-v3-1) | [US Core Condition Problems and Health Concerns](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-problems-health-concerns.html), [US Core Condition Encounter Diagnosis](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-encounter-diagnosis.html) | +| 8 | `medications` | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3-1) | [US Core MedicationRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationrequest.html), [US Core Medication](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medication.html) | +| 9 | `medication_dispenses` | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3-1) (Fill Status) | [US Core MedicationDispense](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationdispense.html) | +| 10 | [`immunizations`](immunizations.md#immunizations) | [Immunizations](https://isp.healthit.gov/taxonomy/term/3021#uscdi-v3-1) | [US Core Immunization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-immunization.html) | +| 11 | [`procedures`](procedures.md#procedures) | [Procedures](https://isp.healthit.gov/taxonomy/term/3071#uscdi-v3-1) | [US Core Procedure](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-procedure.html) | +| 12 | [`service_requests`](procedures.md#service-requests) | [Procedures](https://isp.healthit.gov/taxonomy/term/3071#uscdi-v3-1) (Referral, SDOH Interventions) | [US Core ServiceRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-servicerequest.html) | +| 13 | [`encounters`](encounters.md#encounters) | [Encounter Information](https://isp.healthit.gov/taxonomy/term/2986#uscdi-v3-1) | [US Core Encounter](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-encounter.html) | +| 14 | [`care_team`](care-team.md#care-team) | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3-1) | [US Core CareTeam](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careteam.html) | +| 15 | [`care_plans`](care-plans.md#care-plans) | [Assessment and Plan of Treatment](https://isp.healthit.gov/taxonomy/term/2946#uscdi-v3-1) | [US Core CarePlan](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careplan.html) | +| 16 | [`goals`](goals.md#goals) | [Goals](https://isp.healthit.gov/taxonomy/term/3006#uscdi-v3-1) | [US Core Goal](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-goal.html) | +| 17 | [`coverage`](health-insurance.md#coverage) | [Health Insurance Information](https://isp.healthit.gov/taxonomy/term/3016#uscdi-v3-1) | [US Core Coverage](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-coverage.html) | +| 18 | `documents` | [Clinical Notes](https://isp.healthit.gov/taxonomy/term/2961#uscdi-v3-1) | [US Core DocumentReference](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-documentreference.html) | +| 19 | `diagnostic_reports` | [Clinical Notes](https://isp.healthit.gov/taxonomy/term/2961#uscdi-v3-1), [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3-1), [Diagnostic Imaging](https://isp.healthit.gov/taxonomy/term/2971#uscdi-v3-1) | [US Core DiagnosticReport Lab](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-lab.html), [US Core DiagnosticReport Note](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-note.html) | +| 20 | [`devices`](devices.md#devices) | [Unique Device Identifier(s)](https://isp.healthit.gov/taxonomy/term/3126#uscdi-v3-1) | [US Core Implantable Device](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-implantable-device.html) | +| 21 | `vital_signs` | [Vital Signs](https://isp.healthit.gov/taxonomy/term/3131#uscdi-v3-1) | [US Core Vital Signs](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-vital-signs.html) | +| 22 | `labs` | [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3-1) | [US Core Laboratory Result Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-lab.html), [US Core Specimen](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-specimen.html) | +| 23 | [`social_history`](patient-demographics.md#social-history) | [Health Status Assessments](https://isp.healthit.gov/taxonomy/term/4401#uscdi-v3-1), [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3-1) (Occupation) | [US Core Smoking Status](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-smokingstatus.html), [US Core Observation Occupation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-occupation.html), [US Core Observation Pregnancy Status](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-pregnancystatus.html) | +| 24 | `clinical_observations` | [Clinical Tests](https://isp.healthit.gov/taxonomy/term/2976#uscdi-v3-1), [Diagnostic Imaging](https://isp.healthit.gov/taxonomy/term/2971#uscdi-v3-1), [Health Status Assessments](https://isp.healthit.gov/taxonomy/term/4401#uscdi-v3-1) | [US Core Observation Clinical Result](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-clinical-result.html), [US Core Observation Screening Assessment](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-screening-assessment.html), [US Core Simple Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-simple-observation.html) | diff --git a/docs/data-integration/uscdi/allergies.md b/docs/data-integration/uscdi/allergies.md index 72f254e..77e5bee 100644 --- a/docs/data-integration/uscdi/allergies.md +++ b/docs/data-integration/uscdi/allergies.md @@ -21,7 +21,7 @@ One row per substance per patient. A substance with several reaction manifestati | Column | Required | Format / values | Example | |---|---|---|---| | `patient_identifier` | Yes | patient key | `MRN-4471903` | -| `substance_code` | Yes | RxNorm ingredient or SNOMED CT code, with `substance_system`; RxNorm if omitted [Common substances for allergy and intolerance documentation including refutations](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1186.8) | `7980` penicillin G | +| `substance_code` | Yes | RxNorm ingredient or SNOMED CT code, with `substance_system` (RxNorm assumed when empty) [Common substances for allergy and intolerance documentation including refutations](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http%3A%2F%2Fcts.nlm.nih.gov%2Ffhir%2FValueSet%2F2.16.840.1.113762.1.4.1186.8) | `7980` penicillin G | | `clinical_status` | Yes, unless `verification_status` is `entered-in-error` | `active`, `inactive`, `resolved` [allergyintolerance-clinical](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/allergyintolerance-clinical) | `active` | | `verification_status` | Recommended | `unconfirmed`, `confirmed`, `refuted`, `entered-in-error` [allergyintolerance-verification](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/allergyintolerance-verification) | `confirmed` | | `category` | If available | `food`, `medication`, `environment`, `biologic` [allergy-intolerance-category](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/allergy-intolerance-category) | `medication` | @@ -29,7 +29,6 @@ One row per substance per patient. A substance with several reaction manifestati | `reaction_manifestation_code` | If a reaction is recorded | SNOMED CT code(s), `;`-separated [SNOMED CT Clinical Findings](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/clinical-findings) | `247472004` Wheal | | `onset_date` | If available | datetime | `2019-05-02` | -- `substance_code` is the one coded field with no fallback: a row without it cannot become an AllergyIntolerance. Send `substance_system` as `http://www.nlm.nih.gov/research/umls/rxnorm` or `http://snomed.info/sct`. - **For a medication, send the ingredient (`substance_code`).** Every RxNorm code the value set accepts is an ingredient, single or combination. A code for a specific product or pack, whether an NDC or an RxNorm drug-level code from a pharmacy claim, is not accepted, so roll it up to the ingredient first. For an allergy recorded against a whole drug class, send the SNOMED CT class code. - A row that carries a reaction needs at least one `reaction_manifestation_code`. Manifestation is mandatory inside a reaction. - `clinical_status` and `verification_status` are coupled: FHIR requires `clinical_status` on every row whose `verification_status` is not `entered-in-error`, and forbids it on rows that are. A row that leaves both empty is rejected. Sending `active` on live rows and `resolved` or `inactive` on closed ones satisfies this. diff --git a/docs/data-integration/uscdi/conditions.md b/docs/data-integration/uscdi/conditions.md index fb5883a..76b7571 100644 --- a/docs/data-integration/uscdi/conditions.md +++ b/docs/data-integration/uscdi/conditions.md @@ -51,4 +51,4 @@ One file covers all four USCDI condition flavours — problems, health concerns, | `disability-status` | disability screening finding | health concern + `disability-status` screening category | [us-core-screening-assessment-condition-category](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-screening-assessment-condition-category) | | `cognitive-status` | cognitive screening finding | health concern + `cognitive-status` screening category | [us-core-screening-assessment-condition-category](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-screening-assessment-condition-category) | -These resources are served by [Patient Access](../../interop-apis/patient-access.md), [Provider Access](../../interop-apis/provider-access.md), [Payer-to-Payer](../../interop-apis/payer-to-payer.md), and [Prior Auth](../../prior-auth/README.md). +These resources are served by [Patient Access](../../interop-apis/patient-access.md), [Provider Access](../../interop-apis/provider-access.md), and [Payer-to-Payer](../../interop-apis/payer-to-payer.md). diff --git a/docs/data-integration/uscdi/devices.md b/docs/data-integration/uscdi/devices.md index 479a980..9b3eb7e 100644 --- a/docs/data-integration/uscdi/devices.md +++ b/docs/data-integration/uscdi/devices.md @@ -4,7 +4,7 @@ description: >- Identifier(s) data class to US Core 6.1.0 FHIR. --- -# Unique Device Identifiers +# Device ## Datasets diff --git a/docs/data-integration/uscdi/encounters.md b/docs/data-integration/uscdi/encounters.md index 8451962..0d267ab 100644 --- a/docs/data-integration/uscdi/encounters.md +++ b/docs/data-integration/uscdi/encounters.md @@ -50,7 +50,7 @@ If you already send the [Provider Directory](../provider-directory/README.md) fe | Column | Required | Format / values | Example | |---|---|---|---| | `location_id` | Yes | stable id; the key `encounters` references | `LOC-221` | -| `location_name` | Yes | text | `Riverdale Family Practice` | +| `location_name` | Yes | text | `Family Practice Clinic` | | `managing_org_npi` | Recommended | 10 digits | `1234567893` | | `address_line1` | Recommended | text | `88 River Rd` | | `city` | Recommended | text | `Yonkers` | diff --git a/docs/data-integration/uscdi/goals.md b/docs/data-integration/uscdi/goals.md index 0817c36..42fe29a 100644 --- a/docs/data-integration/uscdi/goals.md +++ b/docs/data-integration/uscdi/goals.md @@ -22,11 +22,11 @@ One row per goal per patient. |---|---|---|---| | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `lifecycle_status` | Yes | `proposed`, `planned`, `accepted`, `active`, `on-hold`, `completed`, `cancelled`, `entered-in-error`, `rejected` [goal-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/goal-status) | `active` | -| `description_code` | Yes | SNOMED CT code, with `description_system`; or plain text [us-core-goal-description](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-goal-description) | `281004` | +| `description_code` | Yes | SNOMED CT or LOINC code, with `description_system`; or plain text [us-core-goal-description](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-goal-description) | `281004` | | `start_date` | If available | date | `2026-04-18` | | `target_date` | If available | date | `2026-10-18` | -- `description_code` is the one field with no fallback: a row without it cannot become a Goal. Send a SNOMED CT code with `description_system` as `http://snomed.info/sct`; the binding is extensible over a value set that spans essentially all of SNOMED CT. A source that records goals only as narrative may put the text itself in `description_code` and leave `description_system` empty. +- `description_code` is the one field with no fallback: a row without it cannot become a Goal. Send a SNOMED CT code (`description_system` = `http://snomed.info/sct`) or a LOINC code (`description_system` = `http://loinc.org`); the binding's own value set spans essentially all of SNOMED CT, and LOINC comes in through its extensibility. A source that records goals only as narrative may put the text itself in `description_code` and leave `description_system` empty. - `lifecycle_status` marks each row: `active` for a goal being pursued, `completed`/`cancelled`/`rejected` for closed ones, `entered-in-error` to retract a record that should never have existed. - `target_date` is the USCDI "Goal Target Date". US Core requires supporting at least one of `Goal.startDate` and `Goal.target.dueDate`, so send whichever your source tracks — either or both are fine. diff --git a/docs/data-integration/uscdi/immunizations.md b/docs/data-integration/uscdi/immunizations.md index 1b7dc67..6705371 100644 --- a/docs/data-integration/uscdi/immunizations.md +++ b/docs/data-integration/uscdi/immunizations.md @@ -25,7 +25,7 @@ One row per administered (or refused) dose per patient. A member with three seas | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `status` | Yes | `completed`, `entered-in-error`, `not-done` [immunization-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/immunization-status) | `completed` | | `status_reason_code` | If `not-done` | SNOMED CT or v3 ActReason code, with `status_reason_system` [immunization-status-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/immunization-status-reason) | `PATOBJ` patient objection | -| `vaccine_code` | Yes | CVX code, with `vaccine_system`; CVX if omitted [CVX Vaccines Administered Vaccine Set](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/vaccine-code) | `140` influenza, seasonal, injectable, preservative free | +| `vaccine_code` | Yes | CVX code, with `vaccine_system` (CVX assumed when empty) [CVX Vaccines Administered Vaccine Set](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/vaccine-code) | `140` influenza, seasonal, injectable, preservative free | | `occurrence_date` | Yes | datetime | `2025-10-02` | | `performer_npi` | If available | 10 digits | `1407006835` | | `primary_source` | Recommended | `true` / `false` | `true` | diff --git a/docs/data-integration/uscdi/patient-demographics.md b/docs/data-integration/uscdi/patient-demographics.md index 5a6a9fb..92203ac 100644 --- a/docs/data-integration/uscdi/patient-demographics.md +++ b/docs/data-integration/uscdi/patient-demographics.md @@ -18,7 +18,15 @@ description: >- ## patients -One row per member. The sections below group its columns. +One row per member, and all the tables in this section describe that same single row: each table is one group of its columns, split up only for readability. Send every column you maintain from every group together in the one `patients` file. + +| Column group | What it carries | +|---|---| +| [Identity](#identity) | the primary key your other rows reference, and how it is issued | +| [Additional identifiers](#additional-identifiers) | other identifiers the member is known by — member number, Medicare or Medicaid ID | +| [Name](#name) | current and previous names | +| [Demographics](#demographics) | gender, sex, birth date, race, ethnicity, tribal affiliation, language | +| [Address and contact](#address-and-contact) | current and previous address, phone, email | ### Identity @@ -43,7 +51,7 @@ One row per member. The sections below group its columns. | `identifier__assigner_org_npi` | Recommended | 10 digits | `1234567893` | - If you use a slot, fill both `value` and `system`. A value without a system is rejected. A slot left blank is ignored. -- Number slots from 2 upward, contiguously. Never 2 and 4. +- `` is a slot number starting at 2, because the [Identity](#identity) columns are slot 1: the first extra identifier goes in `identifier_2_value` + `identifier_2_system`, the next in `identifier_3_…`, and so on. Keep the numbers consecutive — three extra identifiers use slots 2, 3, and 4; skipping a number (2 and 4 with no 3) is invalid. ### Name diff --git a/docs/data-integration/uscdi/procedures.md b/docs/data-integration/uscdi/procedures.md index 66fb10d..1531176 100644 --- a/docs/data-integration/uscdi/procedures.md +++ b/docs/data-integration/uscdi/procedures.md @@ -55,7 +55,7 @@ One row per requested service: a referral, an order, or an SDOH intervention. Th - `reason_code` is why it was requested — the Reason for Referral element. For an SDOH intervention this is the need being addressed, such as food insecurity or lack of transport. - `authored_on` is when the request was written; `occurrence_date` is when the service should happen. - `requester_npi` must match a row in [`practitioners`](care-team.md#practitioners). -- `category` is what marks a row as an SDOH intervention, whatever the service is. The APIs that report on SDOH read it, not `code`. +- `category` set to `sdoh` is what makes a row count as an SDOH intervention. The service in `code` can be anything — a food-bank referral, a transport arrangement — because downstream SDOH reporting selects rows by this category value, not by the service code. Without it, the row is treated as a plain referral or order. These resources are served by [Patient Access](../../interop-apis/patient-access.md), [Provider Access](../../interop-apis/provider-access.md), [Payer-to-Payer](../../interop-apis/payer-to-payer.md), and [Prior Auth](../../prior-auth/README.md). From 65dc5f42d3e2dc9ec1f76416c20105f15f7e3f39 Mon Sep 17 00:00:00 2001 From: glebmark <87950237+glebmark@users.noreply.github.com> Date: Fri, 28 Aug 2026 11:51:06 +0400 Subject: [PATCH 2/2] [HealthSamurai/smartbox#588] labs, medications, organizations --- SUMMARY.md | 2 + docs/data-integration/uscdi/README.md | 8 +-- docs/data-integration/uscdi/care-team.md | 29 ++++++++- docs/data-integration/uscdi/labs.md | 49 +++++++++++++++ docs/data-integration/uscdi/medications.md | 72 ++++++++++++++++++++++ 5 files changed, 154 insertions(+), 6 deletions(-) create mode 100644 docs/data-integration/uscdi/labs.md create mode 100644 docs/data-integration/uscdi/medications.md diff --git a/SUMMARY.md b/SUMMARY.md index e073959..0e5dc66 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -68,6 +68,8 @@ * [Care Team Members](data-integration/uscdi/care-team.md) * [Allergies and Intolerances](data-integration/uscdi/allergies.md) * [Problems](data-integration/uscdi/conditions.md) + * [Medications](data-integration/uscdi/medications.md) + * [Laboratory](data-integration/uscdi/labs.md) * [Immunizations](data-integration/uscdi/immunizations.md) * [Goals](data-integration/uscdi/goals.md) * [Device](data-integration/uscdi/devices.md) diff --git a/docs/data-integration/uscdi/README.md b/docs/data-integration/uscdi/README.md index b8fd019..814aa58 100644 --- a/docs/data-integration/uscdi/README.md +++ b/docs/data-integration/uscdi/README.md @@ -11,12 +11,12 @@ description: >- | 1 | [`patients`](patient-demographics.md#patients) | [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3-1) | [US Core Patient](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-patient.html) (+ race, ethnicity, sex, tribal extensions) | | 2 | [`related_persons`](patient-demographics.md#related-persons) | [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3-1) | [US Core RelatedPerson](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-relatedperson.html) | | 3 | [`practitioners`](care-team.md#practitioners) | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#providers) | [US Core Practitioner](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitioner.html), [US Core PractitionerRole](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitionerrole.html) | -| 4 | `organizations` | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Organization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-organization.html) | +| 4 | [`organizations`](care-team.md#organizations) | [Care Team Members](https://isp.healthit.gov/taxonomy/term/2956#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Organization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-organization.html) | | 5 | [`locations`](encounters.md#locations) | [Encounter Information](https://isp.healthit.gov/taxonomy/term/2986#uscdi-v3-1) (ref), may come from [Provider Directory](../provider-directory/README.md#facilities) | [US Core Location](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-location.html) | | 6 | [`allergies`](allergies.md#allergies) | [Allergies and Intolerances](https://isp.healthit.gov/taxonomy/term/2941#uscdi-v3-1) | [US Core AllergyIntolerance](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-allergyintolerance.html) | | 7 | [`conditions`](conditions.md#conditions) | [Problems](https://isp.healthit.gov/taxonomy/term/3066#uscdi-v3-1) | [US Core Condition Problems and Health Concerns](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-problems-health-concerns.html), [US Core Condition Encounter Diagnosis](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-condition-encounter-diagnosis.html) | -| 8 | `medications` | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3-1) | [US Core MedicationRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationrequest.html), [US Core Medication](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medication.html) | -| 9 | `medication_dispenses` | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3-1) (Fill Status) | [US Core MedicationDispense](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationdispense.html) | +| 8 | [`medications`](medications.md#medications) | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3-1) | [US Core MedicationRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationrequest.html), [US Core Medication](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medication.html) | +| 9 | [`medication_dispenses`](medications.md#medication-dispenses) | [Medications](https://isp.healthit.gov/taxonomy/term/3036#uscdi-v3-1) (Fill Status) | [US Core MedicationDispense](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationdispense.html) | | 10 | [`immunizations`](immunizations.md#immunizations) | [Immunizations](https://isp.healthit.gov/taxonomy/term/3021#uscdi-v3-1) | [US Core Immunization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-immunization.html) | | 11 | [`procedures`](procedures.md#procedures) | [Procedures](https://isp.healthit.gov/taxonomy/term/3071#uscdi-v3-1) | [US Core Procedure](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-procedure.html) | | 12 | [`service_requests`](procedures.md#service-requests) | [Procedures](https://isp.healthit.gov/taxonomy/term/3071#uscdi-v3-1) (Referral, SDOH Interventions) | [US Core ServiceRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-servicerequest.html) | @@ -29,6 +29,6 @@ description: >- | 19 | `diagnostic_reports` | [Clinical Notes](https://isp.healthit.gov/taxonomy/term/2961#uscdi-v3-1), [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3-1), [Diagnostic Imaging](https://isp.healthit.gov/taxonomy/term/2971#uscdi-v3-1) | [US Core DiagnosticReport Lab](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-lab.html), [US Core DiagnosticReport Note](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-diagnosticreport-note.html) | | 20 | [`devices`](devices.md#devices) | [Unique Device Identifier(s)](https://isp.healthit.gov/taxonomy/term/3126#uscdi-v3-1) | [US Core Implantable Device](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-implantable-device.html) | | 21 | `vital_signs` | [Vital Signs](https://isp.healthit.gov/taxonomy/term/3131#uscdi-v3-1) | [US Core Vital Signs](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-vital-signs.html) | -| 22 | `labs` | [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3-1) | [US Core Laboratory Result Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-lab.html), [US Core Specimen](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-specimen.html) | +| 22 | [`labs`](labs.md#labs) | [Laboratory](https://isp.healthit.gov/taxonomy/term/3026#uscdi-v3-1) | [US Core Laboratory Result Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-lab.html), [US Core Specimen](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-specimen.html) | | 23 | [`social_history`](patient-demographics.md#social-history) | [Health Status Assessments](https://isp.healthit.gov/taxonomy/term/4401#uscdi-v3-1), [Patient Demographics/Information](https://isp.healthit.gov/taxonomy/term/3061#uscdi-v3-1) (Occupation) | [US Core Smoking Status](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-smokingstatus.html), [US Core Observation Occupation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-occupation.html), [US Core Observation Pregnancy Status](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-pregnancystatus.html) | | 24 | `clinical_observations` | [Clinical Tests](https://isp.healthit.gov/taxonomy/term/2976#uscdi-v3-1), [Diagnostic Imaging](https://isp.healthit.gov/taxonomy/term/2971#uscdi-v3-1), [Health Status Assessments](https://isp.healthit.gov/taxonomy/term/4401#uscdi-v3-1) | [US Core Observation Clinical Result](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-clinical-result.html), [US Core Observation Screening Assessment](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-screening-assessment.html), [US Core Simple Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-simple-observation.html) | diff --git a/docs/data-integration/uscdi/care-team.md b/docs/data-integration/uscdi/care-team.md index a702be6..c1bbdeb 100644 --- a/docs/data-integration/uscdi/care-team.md +++ b/docs/data-integration/uscdi/care-team.md @@ -1,7 +1,7 @@ --- description: >- - Columns for practitioners and care_team, mapped from the USCDI v3.1 Care Team - Member(s) data class to US Core 6.1.0 FHIR. + Columns for practitioners, organizations, and care_team, mapped from the + USCDI v3.1 Care Team Member(s) data class to US Core 6.1.0 FHIR. --- # Care Team Members @@ -13,6 +13,7 @@ description: >- | Dataset | US Core 6.1.0 target profile(s) | |---|---| | [`practitioners`](#practitioners) | [US Core Practitioner](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitioner.html), [US Core PractitionerRole](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-practitionerrole.html) | +| [`organizations`](#organizations) | [US Core Organization](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-organization.html) | | [`care_team`](#care-team) | [US Core CareTeam](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-careteam.html) | ## practitioners @@ -35,6 +36,30 @@ If you already send the [Provider Directory](../provider-directory/README.md) fe | `role_period_start` | If available | date | `2021-04-01` | | `role_period_end` | If available | date | | +## organizations + +One row per organization: a practice, hospital, pharmacy, or payer that other rows reference by NPI — [`practitioners`](#practitioners) via `primary_org_npi`, `encounters` via `service_provider_npi`, `medication_dispenses` via `pharmacy_org_npi`. + +If you already send the [Provider Directory](../provider-directory/README.md#facilities) feed, list here only the organizations missing from it. + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `org_npi` | Yes | 10 digits, or another stable id with `org_identifier_system` | `1234567893` | +| `org_identifier_system` | If `org_npi` is not an NPI | URI of the issuing system, a URL you control or an OID; NPI (`http://hl7.org/fhir/sid/us-npi`) assumed when empty | `http://acme.org/org-ids` | +| `org_name` | Yes | text | `Family Medical Group` | +| `active` | Recommended | `true` / `false` (`true` assumed when empty); `false` retires an organization without deleting it | `true` | +| `org_type_code` | If available | `prov` provider, `pay` payer, `ins` insurance company, `dept` hospital department, `bus` non-healthcare business [organization-type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/organization-type) | `prov` | +| `telecom_code` | Recommended | `phone`, `fax`, `email`, `pager`, `url`, `sms`, `other` [contact-point-system](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/contact-point-system) | `phone` | +| `telecom_value` | Recommended | the number, address, or URL itself | `5551234567` | +| `address_line1` | Recommended | text | `225 Broadway` | +| `city` | Recommended | text | `New York` | +| `state` | Recommended | 2-letter USPS [USPS states](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-usps-state) | `NY` | +| `zip` | Recommended | 5 or 9 digits, as a string | `10007` | + +- `org_npi` is the key every other dataset uses to point at an organization. Send the NPI whenever the organization has one — US Core requires systems to support NPIs on organizations. An organization without an NPI, such as a community group a referral points to, may use another identifier that stays stable across deliveries; then `org_identifier_system` names who issued it, the same way `patient_identifier_system` does for members. +- `telecom_code` and `telecom_value` travel together: FHIR requires the system code whenever a contact value is sent, so a `telecom_value` with an empty `telecom_code` is rejected. +- FHIR requires `name` and `active` on every Organization, so a row without `org_name` is rejected, and an empty `active` is taken as `true`. + ## care_team One row per patient and team member. diff --git a/docs/data-integration/uscdi/labs.md b/docs/data-integration/uscdi/labs.md new file mode 100644 index 0000000..7767088 --- /dev/null +++ b/docs/data-integration/uscdi/labs.md @@ -0,0 +1,49 @@ +--- +description: >- + Columns for labs, mapped from the USCDI v3.1 Laboratory data class to US Core + 6.1.0 FHIR. +--- + +# Laboratory + +## Datasets + +[US Core 6.1.0](https://hl7.org/fhir/us/core/STU6.1/) maps each [USCDI](https://isp.healthit.gov/united-states-core-data-interoperability-uscdi#uscdi-v3-1) element to FHIR. + +| Dataset | US Core 6.1.0 target profile(s) | +|---|---| +| [`labs`](#labs) | [US Core Laboratory Result Observation](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-lab.html), [US Core Specimen](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-specimen.html) | + +## labs + +One row per analyte result. A panel flattens: each member analyte is its own row, grouped back together by a shared `diagnostic_report_id`. The FHIR category is fixed to `laboratory` — non-lab test results belong in `clinical_observations`. + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `patient_identifier` | Yes | patient key | `MRN-4471903` | +| `status` | Yes | `registered`, `preliminary`, `final`, `amended`, `corrected`, `cancelled`, `entered-in-error`, `unknown` [observation-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/observation-status) | `final` | +| `loinc_code` | Yes | LOINC [us-core-laboratory-test-codes](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-laboratory-test-codes) | `2339-0` glucose [mass/volume] in blood | +| `value_quantity` | If numeric | decimal | `104` | +| `unit` | If `value_quantity` | UCUM [ucum-common](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/ucum-common) | `mg/dL` | +| `value_comparator` | If censored | `<`, `<=`, `>=`, `>` [quantity-comparator](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/quantity-comparator) | | +| `value_string` | If non-numeric | text | `POSITIVE` | +| `value_code` | If coded | SNOMED CT code, with `value_system` (SNOMED CT assumed when empty) | | +| `data_absent_reason` | If no value | `unknown`, `not-performed`, `error`, etc. [data-absent-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/data-absent-reason) | | +| `interpretation` | If available | `H` high, `L` low, `N` normal, `A` abnormal [observation-interpretation](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/observation-interpretation) | `H` | +| `reference_range_low` | If available | decimal | `70` | +| `reference_range_high` | If available | decimal | `99` | +| `effective_datetime` | Recommended | datetime, at least to the day | `2026-04-18T08:40:00-04:00` | +| `specimen_type_code` | If available | SNOMED CT specimen code [Specimen Type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1099.54&server=https://tx.fhir.org/r4) | `119297000` blood specimen | +| `diagnostic_report_id` | If available | `diagnostic_reports` key | `DR-771` | +| `performer_npi` | If available | 10 digits | `1407006835` | + +- `loinc_code` is the USCDI Tests element and the one coded field with no fallback: a row without it cannot become an Observation. The binding accepts any laboratory LOINC code (`http://loinc.org` assumed). +- **Every row needs a result or a reason it is missing.** Send exactly one of `value_quantity` (+ `unit`), `value_string`, or `value_code`; when the source has none — the test was cancelled, the specimen was unsatisfactory — `data_absent_reason` becomes required. A row with neither is rejected. +- `unit` is not free text: US Core requires UCUM for quantity results. `value_code` should be SNOMED CT, e.g. `260385009` Negative for a coded qualitative result. +- A censored numeric result — below or above the assay's detection limit — stays structured: `<0.5` is `value_quantity` `0.5` with `value_comparator` `<`, not a `value_string`. +- `interpretation` and the `reference_range_*` pair go beyond the USCDI v3.1 floor (they joined USCDI in v4), but pass them through whenever your source has them — they are what makes a bare number readable. +- `specimen_type_code` is the USCDI Specimen Type element; it becomes a companion US Core Specimen resource the Observation points at, not a separate dataset you deliver. +- `diagnostic_report_id` groups the analytes of one panel under a report in the `diagnostic_reports` dataset. A lab row is complete without it. +- `performer_npi` is the resulting lab or clinician and must match a row in [`practitioners`](care-team.md#practitioners) or [`organizations`](care-team.md#organizations). + +These resources are served by [Patient Access](../../interop-apis/patient-access.md), [Provider Access](../../interop-apis/provider-access.md), and [Payer-to-Payer](../../interop-apis/payer-to-payer.md). diff --git a/docs/data-integration/uscdi/medications.md b/docs/data-integration/uscdi/medications.md new file mode 100644 index 0000000..6815d59 --- /dev/null +++ b/docs/data-integration/uscdi/medications.md @@ -0,0 +1,72 @@ +--- +description: >- + Columns for medications and medication_dispenses, mapped from the USCDI v3.1 + Medications data class to US Core 6.1.0 FHIR. +--- + +# Medications + +## Datasets + +[US Core 6.1.0](https://hl7.org/fhir/us/core/STU6.1/) maps each [USCDI](https://isp.healthit.gov/united-states-core-data-interoperability-uscdi#uscdi-v3-1) element to FHIR. + +| Dataset | US Core 6.1.0 target profile(s) | +|---|---| +| [`medications`](#medications) | [US Core MedicationRequest](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationrequest.html) | +| [`medication_dispenses`](#medication-dispenses) | [US Core MedicationDispense](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-medicationdispense.html) | + +## medications + +One row per medication order: the prescriber's intent, with drug, dose, and indication. **For most payers this file is sparse or empty** — orders live in EHR and e-prescribing systems, not in claims. If your medication data comes from pharmacy claims, it belongs in [`medication_dispenses`](#medication-dispenses); populate this file only with order-level data you actually hold. + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `patient_identifier` | Yes | patient key | `MRN-4471903` | +| `status` | Yes | `active`, `on-hold`, `cancelled`, `completed`, `entered-in-error`, `stopped`, `draft`, `unknown` [medicationrequest-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/medicationrequest-status) | `active` | +| `intent` | Yes | `proposal`, `plan`, `order`, `original-order`, `reflex-order`, `filler-order`, `instance-order`, `option` [medicationrequest-intent](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/medicationrequest-intent) | `order` | +| `medication_code` | Yes | RxNorm drug-level code, with `medication_system` (RxNorm assumed when empty) [Medication Clinical Drug](https://vsac.nlm.nih.gov/valueset/2.16.840.1.113762.1.4.1010.4/expansion) | `310965` ibuprofen 200 MG oral tablet | +| `category` | If available | `inpatient`, `outpatient`, `community`, `discharge` [medicationrequest-category](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/medicationrequest-category) | `outpatient` | +| `reported` | Recommended | `true` / `false` | `false` | +| `authored_on` | Recommended | datetime | `2026-05-30` | +| `requester_npi` | Recommended | 10 digits | `1407006835` | +| `encounter_id` | If applicable | `encounters` key | `ENC-9912` | +| `dosage_text` | Recommended | the sig, free text | `1 tab PO daily` | +| `dose_value` | If available | decimal | `200` | +| `dose_unit` | If `dose_value` | UCUM [ucum-common](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/ucum-common) | `mg` | +| `refills_allowed` | If available | integer | `3` | +| `dispense_quantity_value` | If available | decimal | `30` | +| `dispense_quantity_unit` | If `dispense_quantity_value` | UCUM [ucum-common](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/ucum-common) | `{tbl}` | +| `indication_code` | If available | SNOMED CT or ICD-10-CM code, with `indication_system` (SNOMED CT assumed when empty) [us-core-condition-code](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-condition-code) | `38341003` hypertensive disorder | + +- `medication_code` is the one coded field with no fallback: a row without it cannot become a MedicationRequest. The value set holds RxNorm codes at the prescribable-product level — a clinical or branded drug, not the bare ingredient. Send `medication_system` as `http://www.nlm.nih.gov/research/umls/rxnorm`. +- `status` carries history: closed orders arrive as `completed`, `stopped`, or `cancelled`; `entered-in-error` retracts a record that should never have existed. +- `reported` set to `true` marks an order known secondhand — reported by the member or imported from another system — rather than authored in the system that sent it. +- `dosage_text` is the sig as written and the most valuable of the dose columns; `dose_value` + `dose_unit` are its structured counterpart, the USCDI Dose and Dose Unit of Measure elements. UCUM count units use curly braces: `{tbl}` tablets. +- `refills_allowed` and the `dispense_quantity_*` pair describe what the order authorizes the pharmacy to dispense — refills and amount per fill. +- `requester_npi` is the prescriber and must match a row in [`practitioners`](care-team.md#practitioners). +- The row's `record_id` is the key that `authorizing_prescription_id` in [`medication_dispenses`](#medication-dispenses) points back to. + +## medication_dispenses + +One row per fill: what the pharmacy actually handed over. **For a payer this is usually the primary medication file** — pharmacy claims are fill records. It carries the USCDI Medications (Fill Status) element and stays distinct from the order in [`medications`](#medications). + +| Column | Required | Format / values | Example | +|---|---|---|---| +| `patient_identifier` | Yes | patient key | `MRN-4471903` | +| `status` | Yes | `preparation`, `in-progress`, `cancelled`, `on-hold`, `completed`, `entered-in-error`, `stopped`, `declined`, `unknown` [medicationdispense-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/medicationdispense-status) | `completed` | +| `medication_code` | Yes | RxNorm drug-level code, with `medication_system` (RxNorm assumed when empty) [Medication Clinical Drug](https://vsac.nlm.nih.gov/valueset/2.16.840.1.113762.1.4.1010.4/expansion) | `310965` ibuprofen 200 MG oral tablet | +| `type_code` | If available | fill type: `FF` first fill, `RF` refill, `EM` emergency supply, `UD` unit dose [ActPharmacySupplyType](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://terminology.hl7.org/ValueSet/v3-ActPharmacySupplyType) | `RF` | +| `pharmacy_org_npi` | Recommended | 10 digits | `1234567893` | +| `performer_npi` | If available | 10 digits, the dispensing pharmacist | `1407006835` | +| `authorizing_prescription_id` | If available | `medications` `record_id` | `MED-77120` | +| `quantity_value` | If available | decimal | `30` | +| `quantity_unit` | If `quantity_value` | UCUM [ucum-common](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/ucum-common) | `{tbl}` | +| `when_handed_over` | If available | datetime | `2026-06-01` | +| `dosage_text` | If available | the sig, free text | `1 tab PO daily` | + +- `status` is the Fill Status element: `completed` for a fill picked up, `in-progress` or `preparation` for one underway, `declined` for one refused, `entered-in-error` to retract. The binding is required, so a value outside the list is rejected. +- A pharmacy-claim row that carries only an NDC may send it with `medication_system` as `http://hl7.org/fhir/sid/ndc`; Payerbox crosswalks it to the RxNorm coding US Core requires. +- `pharmacy_org_npi` is the dispensing pharmacy and `performer_npi` the dispensing pharmacist, when your source records one; both become `MedicationDispense.performer.actor` and must match a row in [`organizations`](care-team.md#organizations) and [`practitioners`](care-team.md#practitioners) respectively. Pharmacy claims usually identify only the store — sending just `pharmacy_org_npi` is fine. +- `when_handed_over` is when the medication left the pharmacy — for a claim, the fill date. + +These resources are served by [Patient Access](../../interop-apis/patient-access.md), [Provider Access](../../interop-apis/provider-access.md), and [Payer-to-Payer](../../interop-apis/payer-to-payer.md).