docs(data-integration): one reference rule, and scope the row key to its feed

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,,,,,

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,

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

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` |

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` |

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.

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` |