From 1e5bc3e860d6d374b6ae144b277cf2c6cb1be1fe Mon Sep 17 00:00:00 2001 From: Akim Khalitov Date: Thu, 27 Aug 2026 21:25:01 +0400 Subject: [PATCH] docs(data-integration): one reference rule, and scope the row key to its feed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Row keys claimed every row carries record_id, but the Provider Directory feed has none: it keys on npi, network_id and plan_id. Both row rules now say which feed they govern, as History already did. Four foreign keys resolved against record_id and four against the target's own key, with nothing on the page saying which did what. Two of those keys earned it — patient_identifier and encounter_id have _system companions and become Patient.identifier and Encounter.identifier. The other two did not: location_id and report_id have no system, never reach FHIR, and exist only to be pointed at, which is what record_id is for. diagnostic_reports even carried report_id equal to record_id on every row. Dropping them leaves one rule with two stated exceptions, and locations keeps the LOC-221 value encounters and practitioners already reference. --- assets/data-integration/diagnostic_reports.csv | 8 ++++---- assets/data-integration/locations.csv | 6 +++--- docs/data-integration/README.md | 3 ++- docs/data-integration/uscdi/care-team.md | 2 +- docs/data-integration/uscdi/clinical-notes.md | 1 - docs/data-integration/uscdi/clinical-tests.md | 2 +- docs/data-integration/uscdi/encounters.md | 3 +-- 7 files changed, 12 insertions(+), 13 deletions(-) diff --git a/assets/data-integration/diagnostic_reports.csv b/assets/data-integration/diagnostic_reports.csv index af76e94..57ce966 100644 --- a/assets/data-integration/diagnostic_reports.csv +++ b/assets/data-integration/diagnostic_reports.csv @@ -1,4 +1,4 @@ -record_id,report_id,patient_identifier,report_kind,status,code,code_system,category_code,effective_datetime,issued,performer_npi,attachment_file,encounter_id,is_deleted -DR-771,DR-771,MRN-4471903,lab,final,24323-8,http://loinc.org,LAB,2026-04-18T08:40:00-04:00,2026-04-18T12:00:00-04:00,9999999993,,ENC-9912, -DR-772,DR-772,MRN-7782200,note,final,39053-4,http://loinc.org,RAD,2026-02-03T09:15:00-05:00,,,attachments/DR-0772.pdf,ENC-9913, -DR-773,DR-773,MRN-4471903,lab,preliminary,24323-8,http://loinc.org,LAB,2026-05-20T07:00:00-04:00,,,,, +record_id,patient_identifier,report_kind,status,code,code_system,category_code,effective_datetime,issued,performer_npi,attachment_file,encounter_id,is_deleted +DR-771,MRN-4471903,lab,final,24323-8,http://loinc.org,LAB,2026-04-18T08:40:00-04:00,2026-04-18T12:00:00-04:00,9999999993,,ENC-9912, +DR-772,MRN-7782200,note,final,39053-4,http://loinc.org,RAD,2026-02-03T09:15:00-05:00,,,attachments/DR-0772.pdf,ENC-9913, +DR-773,MRN-4471903,lab,preliminary,24323-8,http://loinc.org,LAB,2026-05-20T07:00:00-04:00,,,,, diff --git a/assets/data-integration/locations.csv b/assets/data-integration/locations.csv index a6fd448..ec3832f 100644 --- a/assets/data-integration/locations.csv +++ b/assets/data-integration/locations.csv @@ -1,3 +1,3 @@ -record_id,location_id,location_name,managing_org_npi,address_line1,city,state,zip,is_deleted -LOC-0001,LOC-221,Anytown Family Practice,9999999993,123 Main St,Anytown,NY,12345, -LOC-0002,LOC-884,Anytown Imaging Center,,9 Pine Ave,Anytown,NY,12345, +record_id,location_name,managing_org_npi,address_line1,city,state,zip,is_deleted +LOC-221,Anytown Family Practice,9999999993,123 Main St,Anytown,NY,12345, +LOC-884,Anytown Imaging Center,,9 Pine Ave,Anytown,NY,12345, diff --git a/docs/data-integration/README.md b/docs/data-integration/README.md index 682b7a6..957c904 100644 --- a/docs/data-integration/README.md +++ b/docs/data-integration/README.md @@ -23,7 +23,8 @@ graph LR | 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. | | 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. | -| Row keys | Every row carries `record_id`, your stable key for it. It is what an upload updates in place, so keep it stable across deliveries. `is_deleted` set to `true` retracts the row it names. | +| Row keys (USCDI feed) | Every row carries `record_id`, your stable key for it. It is what an upload updates in place, so keep it stable across deliveries. `is_deleted` set to `true` retracts the row it names. | +| References (USCDI feed) | A column that points at a row in another dataset holds that row's `record_id`: `location_id`, `panel_id`, `diagnostic_report_id` and the rest. Two carry the target's own identifier instead, because the FHIR resource is identified by it too: `patient_identifier` and `encounter_id`. | | Code systems | Every coded column has a companion `_system` column holding the code system URI: `substance_code` with `substance_system`, `vaccine_code` with `vaccine_system`, and so on. Leave it blank to accept the default named in that column's row. | ## Built on US Core diff --git a/docs/data-integration/uscdi/care-team.md b/docs/data-integration/uscdi/care-team.md index 09cd080..9ba30ad 100644 --- a/docs/data-integration/uscdi/care-team.md +++ b/docs/data-integration/uscdi/care-team.md @@ -33,7 +33,7 @@ practitioners.csv Data template with example rows | `specialty_nucc` | Recommended | NUCC taxonomy code(s), `;`-separated [Healthcare Provider Taxonomy](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.114222.4.11.1066&server=https://tx.fhir.org/r4) | `207R00000X` | | `primary_org_npi` | Recommended | 10 digits | `9999999993` | | `practitioner_role_code` | Recommended | SNOMED CT or v3 participation-function code [Care Team Member Function](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1099.30&server=https://tx.fhir.org/r4) | `PCP` primary care physician | -| `location_id` | Recommended | `locations` key | `LOC-221` | +| `location_id` | Recommended | `record_id` of the `locations` row | `LOC-221` | | `phone` | Recommended | 10 digits | `5551234567` | | `email` | If available | email address | | | `role_period_start` | If available | date | `2021-04-01` | diff --git a/docs/data-integration/uscdi/clinical-notes.md b/docs/data-integration/uscdi/clinical-notes.md index 1750f58..222d614 100644 --- a/docs/data-integration/uscdi/clinical-notes.md +++ b/docs/data-integration/uscdi/clinical-notes.md @@ -61,7 +61,6 @@ diagnostic_reports.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| -| `report_id` | Yes | stable key; the key result rows reference | `DR-771` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `report_kind` | Yes | `lab` or `note` | `lab` | | `status` | Yes | `registered`, `partial`, `preliminary`, `final`, `amended`, `corrected`, `appended`, `cancelled`, `entered-in-error`, `unknown` [diagnostic-report-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/diagnostic-report-status%7C4.0.1) | `final` | diff --git a/docs/data-integration/uscdi/clinical-tests.md b/docs/data-integration/uscdi/clinical-tests.md index e1be1e0..d838cb7 100644 --- a/docs/data-integration/uscdi/clinical-tests.md +++ b/docs/data-integration/uscdi/clinical-tests.md @@ -36,7 +36,7 @@ clinical_observations.csv Data template with example rows | `effective_datetime` | Recommended | datetime | `2026-04-18` | | `performer_npi` | If available | 10 digits | `9999999991` | | `panel_id` | If available | `record_id` of the parent `clinical_observations` row | `CO-1200` | -| `diagnostic_report_id` | If applicable | `report_id` of the `diagnostic_reports` row this result belongs to | `DR-771` | +| `diagnostic_report_id` | If applicable | `record_id` of the `diagnostic_reports` row this result belongs to | `DR-771` | - Send exactly one of `value_quantity`, `value_string`, `value_code` or `data_absent_reason`. A row with a result and an absent reason contradicts itself; a row with neither cannot become an Observation. - `data_absent_reason` is how a screening question that was asked but not answered stays in the record. Leaving the row out instead loses the fact that it was asked. diff --git a/docs/data-integration/uscdi/encounters.md b/docs/data-integration/uscdi/encounters.md index cd457f9..fcfb072 100644 --- a/docs/data-integration/uscdi/encounters.md +++ b/docs/data-integration/uscdi/encounters.md @@ -34,7 +34,7 @@ encounters.csv Data template with example rows | `period_start` | Recommended | datetime | `2026-04-18T09:00:00-04:00` | | `period_end` | Recommended | datetime | `2026-04-18T09:30:00-04:00` | | `reason_code` | If available | SNOMED CT or ICD-10-CM code(s), `;`-separated, with `reason_system`; SNOMED CT if omitted [encounter-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/encounter-reason%7C4.0.1) | `29857009` chest pain | -| `location_id` | Recommended | `locations` key | `LOC-221` | +| `location_id` | Recommended | `record_id` of the `locations` row | `LOC-221` | | `diagnosis_condition_id` | If available | `record_id` of the `conditions` row(s), `;`-separated | `CND-4501` | | `participant_npi` | If available | 10 digits, `;`-separated | `9999999991` | | `participant_type_code` | If available | `ATND` attender, `ADM` admitter, `DIS` discharger, `CON` consultant, `REF` referrer, with `participant_type_system`; v3-ParticipationType if omitted [encounter-participant-type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/encounter-participant-type%7C4.0.1) | `ATND` | @@ -57,7 +57,6 @@ locations.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| -| `location_id` | Yes | stable id; the key `encounters` references | `LOC-221` | | `location_name` | Yes | text | `Anytown Family Practice` | | `managing_org_npi` | Recommended | 10 digits | `9999999993` | | `address_line1` | Recommended | text | `123 Main St` |