HealthSamurai · akim1995 · Aug 27, 2026 · Aug 27, 2026
diff --git a/assets/data-integration/care_team.csv b/assets/data-integration/care_team.csv
@@ -1,4 +1,4 @@
-record_id,patient_identifier,member_npi,member_related_person_id,role_code,status,source_system,last_updated,author_org_npi,is_deleted
-CT-0001,MRN-4471903,9999999991,,223366009,active,,2026-08-19T02:00:00-04:00,,
-CT-0002,MRN-4471903,,RP-3310,223366009,active,,2026-08-19T02:00:00-04:00,,
-CT-0003,MRN-7782200,9999999992,,223366009,inactive,,2026-08-19T02:00:00-04:00,,
+record_id,patient_identifier,member_npi,member_related_person_id,role_code,status,source_system,last_updated,author_org_npi,is_deleted
+CT-0001,MRN-4471903,9999999991,,446050000,active,,2026-08-19T02:00:00-04:00,,
+CT-0002,MRN-4471903,,RP-3310,446050000,active,,2026-08-19T02:00:00-04:00,,
+CT-0003,MRN-7782200,9999999992,,446050000,inactive,,2026-08-19T02:00:00-04:00,,
diff --git a/assets/data-integration/clinical_observations.csv b/assets/data-integration/clinical_observations.csv
@@ -1,6 +1,6 @@
-record_id,patient_identifier,category,status,loinc_code,loinc_system,value_quantity,unit,value_string,value_code,value_system,data_absent_reason,effective_datetime,performer_npi,panel_id,source_system,last_updated,author_org_npi,is_deleted
-CO-1200,MRN-3391077,sdoh,final,76504-0,http://loinc.org,3,{score},,,,,2026-04-18,,,,2026-08-19T02:00:00-04:00,,
-CO-0002,MRN-3391077,sdoh,final,76504-0,http://loinc.org,,,,,,asked-declined,2026-04-18,,CO-1200,,2026-08-19T02:00:00-04:00,,
-CO-0003,MRN-4471903,exam,final,76504-0,http://loinc.org,,,No abnormality detected,,,,2026-04-18,,,,2026-08-19T02:00:00-04:00,,
-CO-0004,MRN-7782200,imaging,final,76504-0,http://loinc.org,,,,44054006,http://snomed.info/sct,,2026-02-03,9999999993,,,2026-08-19T02:00:00-04:00,,
-CO-0005,MRN-5510042,functional-status,final,76504-0,http://loinc.org,18,{score},,,,,2026-01-09,,,,2026-08-19T02:00:00-04:00,,
+record_id,patient_identifier,category,status,loinc_code,loinc_system,value_quantity,unit,value_string,value_code,value_system,data_absent_reason,effective_datetime,performer_npi,panel_id,diagnostic_report_id,source_system,last_updated,author_org_npi,is_deleted
+CO-1200,MRN-3391077,sdoh,final,76504-0,http://loinc.org,3,{score},,,,,2026-04-18,,,,,2026-08-19T02:00:00-04:00,,
+CO-0002,MRN-3391077,sdoh,final,76504-0,http://loinc.org,,,,,,asked-declined,2026-04-18,,CO-1200,,,2026-08-19T02:00:00-04:00,,
+CO-0003,MRN-4471903,exam,final,76504-0,http://loinc.org,,,No abnormality detected,,,,2026-04-18,,,,,2026-08-19T02:00:00-04:00,,
+CO-0004,MRN-7782200,imaging,final,76504-0,http://loinc.org,,,,44054006,http://snomed.info/sct,,2026-02-03,9999999993,,,,2026-08-19T02:00:00-04:00,,
+CO-0005,MRN-5510042,functional-status,final,76504-0,http://loinc.org,18,{score},,,,,2026-01-09,,,,,2026-08-19T02:00:00-04:00,,
diff --git a/assets/data-integration/goals.csv b/assets/data-integration/goals.csv
@@ -1,4 +1,4 @@
 record_id,patient_identifier,lifecycle_status,description_code,description_system,start_date,target_date,source_system,last_updated,author_org_npi,is_deleted
-GL-0001,MRN-4471903,active,281004,http://snomed.info/sct,2026-04-18,2026-10-18,,2026-08-19T02:00:00-04:00,,
-GL-0002,MRN-7782200,completed,281004,http://snomed.info/sct,2025-03-01,2025-09-01,,2026-08-19T02:00:00-04:00,,
-GL-0003,MRN-5510042,proposed,281004,http://snomed.info/sct,,,,2026-08-19T02:00:00-04:00,,
+GL-0001,MRN-4471903,active,289169006,http://snomed.info/sct,2026-04-18,2026-10-18,,2026-08-19T02:00:00-04:00,,
+GL-0002,MRN-7782200,completed,289169006,http://snomed.info/sct,2025-03-01,2025-09-01,,2026-08-19T02:00:00-04:00,,
+GL-0003,MRN-5510042,proposed,289169006,http://snomed.info/sct,,,,2026-08-19T02:00:00-04:00,,
diff --git a/assets/data-integration/patients.csv b/assets/data-integration/patients.csv
@@ -1,6 +1,6 @@
-record_id,patient_identifier,patient_identifier_system,patient_identifier_type,patient_identifier_use,patient_identifier_assigner_org_npi,identifier_2_value,identifier_2_system,identifier_2_type,identifier_2_use,identifier_2_period_start,identifier_2_period_end,identifier_2_assigner_org_npi,last_name,first_name,middle_name,name_suffix,previous_name,gender,sex,birth_date,deceased_date,race_omb_code,race_detailed_code,ethnicity_omb_code,ethnicity_detailed_code,tribal_affiliation_code,preferred_language,address_line1,address_line2,city,state,zip,phone,phone_type,email,previous_address,previous_address_end,source_system,last_updated,author_org_npi,is_deleted
-PT-0001,MRN-4471903,http://example.org/mrns,MR,official,9999999993,HSX9930012,http://example.org/member-ids,MB,official,2024-01-01,2025-12-31,9999999993,Doe,Jane,L,,,female,248152002,1957-03-11,,2106-3,2108-9,2186-5,,,en,123 Main St,Apt 3,Anytown,NY,12345,5551234567,mobile,jane.doe@example.org,,,,2026-08-19T02:00:00-04:00,,
-PT-0002,MRN-5510042,http://example.org/mrns,,,,,,,,,,,Roe,John,,,,male,,,,,,,,,,,,,,,,,,,,,2026-08-19T02:00:00-04:00,,
-PT-0003,MRN-7782200,http://example.org/mrns,,,,,,,,,,,Poe,Ann,,,,female,,1940-02-29,2026-01-14,,,,,,,,,Anytown,NY,12345,,,,,,,2026-08-19T02:00:00-04:00,,
-PT-0004,MRN-3391077,http://example.org/mrns,,,,,,,,,,,Fox,Sam,,,,other,,1988-07-04,,2106-3;2054-5,,2135-2,,,es,9 Pine Ave,,Anytown,NY,12345,,,,,,,2026-08-19T02:00:00-04:00,,
-PT-0005,MRN-4471903,http://example.org/mrns,,,,,,,,,,,Doe,Jane,,,"Smith, Jane",female,,1957-03-11,,,,,,,,123 Main St,,Anytown,NY,12345,,,,"45 Oak St, Anytown, NY, 12345",2024-08-31,,2026-08-19T02:00:00-04:00,,
+record_id,patient_identifier,patient_identifier_system,patient_identifier_type,patient_identifier_use,patient_identifier_assigner_org_npi,identifier_2_value,identifier_2_system,identifier_2_type,identifier_2_use,identifier_2_period_start,identifier_2_period_end,identifier_2_assigner_org_npi,last_name,first_name,middle_name,name_suffix,previous_name,gender,sex,birth_date,deceased_date,race_omb_code,race_detailed_code,ethnicity_omb_code,ethnicity_detailed_code,tribal_affiliation_code,preferred_language,address_line1,address_line2,city,state,zip,phone,phone_type,email,previous_address,previous_address_end,source_system,last_updated,author_org_npi,is_deleted
+PT-0001,MRN-4471903,http://example.org/mrns,MR,official,9999999993,HSX9930012,http://example.org/member-ids,MB,official,2024-01-01,2025-12-31,9999999993,Doe,Jane,L,,,female,248152002,1957-03-11,,2106-3,2108-9,2186-5,,,en,123 Main St,Apt 3,Anytown,NY,12345,5551234567,mobile,jane.doe@example.org,,,,2026-08-19T02:00:00-04:00,,
+PT-0002,MRN-5510042,http://example.org/mrns,,,,,,,,,,,Roe,John,,,,male,,,,,,,,,,,,,,,,,,,,,2026-08-19T02:00:00-04:00,,
+PT-0003,MRN-7782200,http://example.org/mrns,,,,,,,,,,,Poe,Ann,,,,female,,1940-02-29,2026-01-14,,,,,,,,,Anytown,NY,12345,,,,,,,2026-08-19T02:00:00-04:00,,
+PT-0004,MRN-3391077,http://example.org/mrns,,,,,,,,,,,Fox,Sam,,,,other,,1988-07-04,,2106-3;2054-5,,2135-2,,,es,9 Pine Ave,,Anytown,NY,12345,,,,,,,2026-08-19T02:00:00-04:00,,
+PT-0005,MRN-6620518,http://example.org/mrns,,,,,,,,,,,Vale,Kim,,,"Ash, Kim",female,,1957-03-11,,,,,,,,123 Main St,,Anytown,NY,12345,,,,"45 Oak St, Anytown, NY, 12345",2024-08-31,,2026-08-19T02:00:00-04:00,,
diff --git a/assets/data-integration/practitioners.csv b/assets/data-integration/practitioners.csv
@@ -1,4 +1,4 @@
-record_id,npi,last_name,first_name,specialty_nucc,primary_org_npi,practitioner_role_code,location_id,phone,email,role_period_start,role_period_end,source_system,last_updated,author_org_npi,is_deleted
-PRC-0001,9999999991,Roe,Richard,207R00000X,9999999993,doctor,LOC-221,5551234567,,2021-04-01,,,2026-08-19T02:00:00-04:00,,
-PRC-0002,9999999991,Roe,Richard,207R00000X,9999999993,doctor,LOC-884,5554445555,,,,,2026-08-19T02:00:00-04:00,,
-PRC-0003,9999999992,Fox,Dana,,,,,,,,,,2026-08-19T02:00:00-04:00,,
+record_id,npi,last_name,first_name,specialty_nucc,primary_org_npi,practitioner_role_code,location_id,phone,email,role_period_start,role_period_end,source_system,last_updated,author_org_npi,is_deleted
+PRC-0001,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-221,5551234567,,2021-04-01,,,2026-08-19T02:00:00-04:00,,
+PRC-0002,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-884,5554445555,,,,,2026-08-19T02:00:00-04:00,,
+PRC-0003,9999999992,Fox,Dana,,,,,,,,,,2026-08-19T02:00:00-04:00,,
diff --git a/docs/data-integration/uscdi/README.md b/docs/data-integration/uscdi/README.md
@@ -30,5 +30,5 @@ description: >-
 | 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.md#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) |
+| 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), [US Core Observation Pregnancy Intent](https://hl7.org/fhir/us/core/STU6.1/StructureDefinition-us-core-observation-pregnancyintent.html) |
 | 24 | [`clinical_observations`](clinical-tests.md#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) |
diff --git a/docs/data-integration/uscdi/care-plans.md b/docs/data-integration/uscdi/care-plans.md
@@ -31,7 +31,7 @@ care_plans.csv Data template with example rows
 | `period_start` | If available | datetime | `2026-04-18` |
 | `period_end` | If available | datetime | |
 
-- `narrative_text` is the payload of this dataset, not a summary of it. US Core requires the narrative on every CarePlan, so a row without it cannot become one. Send the assessment and the plan as your source holds them; HTML is preserved, plain text is wrapped.
+- `narrative_text` is the payload of this dataset, not a summary of it. US Core must-supports the narrative and requires `text.div` whenever `text` is present, so a row without it produces a CarePlan with nothing to read. Send the assessment and the plan as your source holds them; HTML is preserved, plain text is wrapped.
 - Payerbox sets the `assess-plan` category and the narrative status on every row. Both are fixed by the profile, so there is nothing for you to send.
 - `status` and `intent` are required bindings, so a value outside these lists is rejected. A plan a payer holds is normally `active` with intent `plan`.
 

diff --git a/docs/data-integration/uscdi/care-team.md b/docs/data-integration/uscdi/care-team.md
@@ -32,7 +32,7 @@ practitioners.csv Data template with example rows
 | `first_name` | Recommended | text | `Richard` |
 | `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 | role 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) | `doctor` |
+| `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` |
 | `phone` | Recommended | 10 digits | `5551234567` |
 | `email` | If available | email address | |
@@ -50,9 +50,9 @@ care_team.csv Data template with example rows
 | Column | Required | Format / values | Example |
 |---|---|---|---|
 | `patient_identifier` | Yes | patient key | `MRN-4471903` |
-| `member_npi` | Yes | 10 digits; send this or `member_related_person_id` | `9999999991` |
-| `member_related_person_id` | Yes | `record_id` of the `related_persons` row, for non-clinicians; send this or `member_npi` | `RP-3310` |
-| `role_code` | Yes | SNOMED or NUCC 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) | `223366009` |
+| `member_npi` | Yes, unless `member_related_person_id` is sent | 10 digits | `9999999991` |
+| `member_related_person_id` | Yes, unless `member_npi` is sent | `record_id` of the `related_persons` row, for non-clinicians | `RP-3310` |
+| `role_code` | Yes | 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) | `446050000` primary care physician |
 | `status` | Recommended | `proposed`, `active`, `suspended`, `inactive`, `entered-in-error` [care-team-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/care-team-status%7C4.0.1) | `active` |
 
 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/clinical-notes.md b/docs/data-integration/uscdi/clinical-notes.md
@@ -73,7 +73,7 @@ diagnostic_reports.csv Data template with example rows
 | `attachment_file` | If available | path relative to the delivery root | `attachments/DR-0771.pdf` |
 | `encounter_id` | If applicable | `encounters` key | `ENC-9912` |
 
-- `report_kind` picks the profile: `lab` for a laboratory report, `note` for everything else, including radiology and pathology narratives. The two bind `code` to different value sets, so a lab code on a `note` row is rejected and the reverse too. A wrong `report_kind` is not cosmetic.
+- `report_kind` picks the profile: `lab` for a laboratory report, `note` for everything else, including radiology and pathology narratives. The two bind `code` to different value sets, so a lab code on a `note` row falls outside the binding and the reverse too. Both bindings are extensible, so the code is not rejected, but a wrong `report_kind` silently produces the wrong profile.
 - `attachment_file` carries the narrative report as a file, the same way `documents` does. A lab report with structured results and no narrative needs none.
 - This dataset also serves the Laboratory and Diagnostic Imaging data classes, not only Clinical Notes.
 

diff --git a/docs/data-integration/uscdi/clinical-tests.md b/docs/data-integration/uscdi/clinical-tests.md
@@ -36,6 +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` |
 
 - 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/goals.md b/docs/data-integration/uscdi/goals.md
@@ -26,7 +26,7 @@ goals.csv Data template with example rows
 |---|---|---|---|
 | `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%7C4.0.1) | `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 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) | `289169006` exercising to lose weight |
 | `start_date` | If available | date | `2026-04-18` |
 | `target_date` | If available | date | `2026-10-18` |
 

diff --git a/docs/data-integration/uscdi/health-insurance.md b/docs/data-integration/uscdi/health-insurance.md
@@ -26,8 +26,8 @@ coverage.csv Data template with example rows
 |---|---|---|---|
 | `patient_identifier` | Yes | patient key | `MRN-4471903` |
 | `status` | Yes | `active`, `cancelled`, `draft`, `entered-in-error` [fm-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/fm-status%7C4.0.1) | `active` |
-| `member_id` | Recommended | plan member id | `HSX9930012` |
-| `subscriber_id` | Recommended | text | `HSX9930012` |
+| `member_id` | Yes, unless `subscriber_id` is sent | plan member id | `HSX9930012` |
+| `subscriber_id` | Yes, unless `member_id` is sent | text | `HSX9930012` |
 | `relationship_code` | Yes | `self`, `spouse`, `child`, `other` [subscriber-relationship](https://terminology.hl7.org/CodeSystem-subscriber-relationship.html) | `self` |
 | `coverage_type_code` | Recommended | Source of Payment Typology [Payer Type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.114222.4.11.3591) | `1` Medicare |
 | `payer_org_npi` | Yes | 10 digits, or your payer id | `9999999993` |
@@ -38,4 +38,7 @@ coverage.csv Data template with example rows
 | `period_start` | Recommended | date | `2026-01-01` |
 | `period_end` | Recommended | date | `2026-12-31` |
 
+- Send at least one of `member_id` and `subscriber_id`. US Core requires a member id or a subscriber id on every Coverage, so a row with neither cannot become one.
+- A group or plan name travels with its number: send `group_number` with `group_name`, and `plan_number` with `plan_name`.
+
 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).