From a413884d423faeef8857df396f7c6b53c0eead4b Mon Sep 17 00:00:00 2001 From: Akim Khalitov Date: Thu, 27 Aug 2026 22:09:12 +0400 Subject: [PATCH 1/3] docs(data-integration): let each dataset name its own key MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Row keys said every row carries record_id, which was never true of the Provider Directory feed and sat awkwardly beside the keys four datasets already had: patients kept PT-0001 next to an MRN, encounters and diagnostic_reports carried record_id equal to encounter_id and report_id on every row, and documents ended up with record_id twice, in columns one and five, because the page listed it mid-table as well. Each dataset now names its own key, listed first: allergy_id, condition_id, observation_id and the rest, keeping encounter_id, location_id, report_id and patient_identifier where they already existed. Fourteen tables gained the row that names it — until now only six said what keyed them — and the foreign keys name the column they resolve against, which is the same name in most cases. The convention keeps only what is not per-dataset: the key must stay stable because the resource id derives from it, and is_deleted retracts the row. --- assets/data-integration/allergies.csv | 12 ++++++------ assets/data-integration/care_plans.csv | 8 ++++---- assets/data-integration/care_team.csv | 8 ++++---- assets/data-integration/clinical_observations.csv | 12 ++++++------ assets/data-integration/conditions.csv | 12 ++++++------ assets/data-integration/coverage.csv | 8 ++++---- assets/data-integration/devices.csv | 6 +++--- assets/data-integration/diagnostic_reports.csv | 8 ++++---- assets/data-integration/documents.csv | 8 ++++---- assets/data-integration/encounters.csv | 10 +++++----- assets/data-integration/goals.csv | 8 ++++---- assets/data-integration/immunizations.csv | 8 ++++---- assets/data-integration/locations.csv | 6 +++--- assets/data-integration/patients.csv | 12 ++++++------ assets/data-integration/practitioners.csv | 8 ++++---- assets/data-integration/procedures.csv | 8 ++++---- assets/data-integration/related_persons.csv | 10 +++++----- assets/data-integration/service_requests.csv | 8 ++++---- assets/data-integration/social_history.csv | 12 ++++++------ assets/data-integration/vital_signs.csv | 12 ++++++------ docs/data-integration/README.md | 2 +- docs/data-integration/uscdi/allergies.md | 1 + docs/data-integration/uscdi/care-plans.md | 1 + docs/data-integration/uscdi/care-team.md | 4 +++- docs/data-integration/uscdi/clinical-notes.md | 5 ++--- docs/data-integration/uscdi/clinical-tests.md | 3 ++- docs/data-integration/uscdi/conditions.md | 1 + docs/data-integration/uscdi/devices.md | 1 + docs/data-integration/uscdi/encounters.md | 6 +++--- docs/data-integration/uscdi/goals.md | 1 + docs/data-integration/uscdi/health-insurance.md | 1 + docs/data-integration/uscdi/immunizations.md | 1 + docs/data-integration/uscdi/patient-demographics.md | 2 ++ docs/data-integration/uscdi/procedures.md | 4 +++- docs/data-integration/uscdi/vital-signs.md | 1 + 35 files changed, 116 insertions(+), 102 deletions(-) diff --git a/assets/data-integration/allergies.csv b/assets/data-integration/allergies.csv index 105e862..3589b7b 100644 --- a/assets/data-integration/allergies.csv +++ b/assets/data-integration/allergies.csv @@ -1,6 +1,6 @@ -record_id,patient_identifier,substance_code,substance_system,clinical_status,verification_status,category,criticality,reaction_manifestation_code,onset_date,is_deleted -AL-0001,MRN-4471903,7980,,active,confirmed,medication,high,247472004,2019-05-02, -AL-0002,MRN-5510042,7980,,active,,,,,, -AL-0003,MRN-7782200,716186003,http://snomed.info/sct,active,confirmed,,,,, -AL-0004,MRN-3391077,409137002,http://snomed.info/sct,active,confirmed,,,,, -AL-0005,MRN-4471903,7980,,,entered-in-error,,,,, +allergy_id,patient_identifier,substance_code,substance_system,clinical_status,verification_status,category,criticality,reaction_manifestation_code,onset_date,is_deleted +AL-0001,MRN-4471903,7980,,active,confirmed,medication,high,247472004,2019-05-02, +AL-0002,MRN-5510042,7980,,active,,,,,, +AL-0003,MRN-7782200,716186003,http://snomed.info/sct,active,confirmed,,,,, +AL-0004,MRN-3391077,409137002,http://snomed.info/sct,active,confirmed,,,,, +AL-0005,MRN-4471903,7980,,,entered-in-error,,,,, diff --git a/assets/data-integration/care_plans.csv b/assets/data-integration/care_plans.csv index bbc2f15..1c3d475 100644 --- a/assets/data-integration/care_plans.csv +++ b/assets/data-integration/care_plans.csv @@ -1,4 +1,4 @@ -record_id,patient_identifier,narrative_text,status,intent,period_start,period_end,is_deleted -CP-0001,MRN-4471903,Assessment: … Plan: …,active,plan,2026-04-18,, -CP-0002,MRN-7782200,Assessment: … Plan: …,completed,plan,2025-01-06,2025-12-31, -CP-0003,MRN-5510042,Assessment: … Plan: …,draft,proposal,,, +care_plan_id,patient_identifier,narrative_text,status,intent,period_start,period_end,is_deleted +CP-0001,MRN-4471903,Assessment: … Plan: …,active,plan,2026-04-18,, +CP-0002,MRN-7782200,Assessment: … Plan: …,completed,plan,2025-01-06,2025-12-31, +CP-0003,MRN-5510042,Assessment: … Plan: …,draft,proposal,,, diff --git a/assets/data-integration/care_team.csv b/assets/data-integration/care_team.csv index 11b1a6c..f1289fc 100644 --- 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,is_deleted -CT-0001,MRN-4471903,9999999991,,446050000,active, -CT-0002,MRN-4471903,,RP-3310,446050000,active, -CT-0003,MRN-7782200,9999999992,,446050000,inactive, +care_team_id,patient_identifier,member_npi,member_related_person_id,role_code,status,is_deleted +CT-0001,MRN-4471903,9999999991,,446050000,active, +CT-0002,MRN-4471903,,RP-3310,446050000,active, +CT-0003,MRN-7782200,9999999992,,446050000,inactive, diff --git a/assets/data-integration/clinical_observations.csv b/assets/data-integration/clinical_observations.csv index c06acbb..ff4a76f 100644 --- 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,diagnostic_report_id,is_deleted -CO-1200,MRN-3391077,sdoh,final,76504-0,http://loinc.org,3,{score},,,,,2026-04-18,,,, -CO-0002,MRN-3391077,sdoh,final,76504-0,http://loinc.org,,,,,,asked-declined,2026-04-18,,CO-1200,, -CO-0003,MRN-4471903,exam,final,76504-0,http://loinc.org,,,No abnormality detected,,,,2026-04-18,,,, -CO-0004,MRN-7782200,imaging,final,76504-0,http://loinc.org,,,,44054006,http://snomed.info/sct,,2026-02-03,9999999993,,, -CO-0005,MRN-5510042,functional-status,final,76504-0,http://loinc.org,18,{score},,,,,2026-01-09,,,, +observation_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,is_deleted +CO-1200,MRN-3391077,sdoh,final,76504-0,http://loinc.org,3,{score},,,,,2026-04-18,,,, +CO-0002,MRN-3391077,sdoh,final,76504-0,http://loinc.org,,,,,,asked-declined,2026-04-18,,CO-1200,, +CO-0003,MRN-4471903,exam,final,76504-0,http://loinc.org,,,No abnormality detected,,,,2026-04-18,,,, +CO-0004,MRN-7782200,imaging,final,76504-0,http://loinc.org,,,,44054006,http://snomed.info/sct,,2026-02-03,9999999993,,, +CO-0005,MRN-5510042,functional-status,final,76504-0,http://loinc.org,18,{score},,,,,2026-01-09,,,, diff --git a/assets/data-integration/conditions.csv b/assets/data-integration/conditions.csv index 1865f8f..3d3abf9 100644 --- a/assets/data-integration/conditions.csv +++ b/assets/data-integration/conditions.csv @@ -1,6 +1,6 @@ -record_id,patient_identifier,category,code,code_system,clinical_status,verification_status,onset_date,abatement_date,recorded_date,asserted_date,encounter_id,is_deleted -CND-0001,MRN-4471903,problem-list-item,44054006,http://snomed.info/sct,active,confirmed,2021-08-14,,2021-08-15,,, -CND-0002,MRN-4471903,problem-list-item,44054006,http://snomed.info/sct,resolved,confirmed,2019-02-03,2023-11-30,2019-02-04,,, -CND-4501,MRN-7782200,encounter-diagnosis,44054006,http://snomed.info/sct,active,confirmed,,,2026-04-18,,ENC-9913, -CND-0004,MRN-5510042,health-concern,44054006,http://snomed.info/sct,active,,,,2026-01-09,,, -CND-0005,MRN-3391077,sdoh,44054006,http://snomed.info/sct,active,,,,2026-03-02,,, +condition_id,patient_identifier,category,code,code_system,clinical_status,verification_status,onset_date,abatement_date,recorded_date,asserted_date,encounter_id,is_deleted +CND-0001,MRN-4471903,problem-list-item,44054006,http://snomed.info/sct,active,confirmed,2021-08-14,,2021-08-15,,, +CND-0002,MRN-4471903,problem-list-item,44054006,http://snomed.info/sct,resolved,confirmed,2019-02-03,2023-11-30,2019-02-04,,, +CND-4501,MRN-7782200,encounter-diagnosis,44054006,http://snomed.info/sct,active,confirmed,,,2026-04-18,,ENC-9913, +CND-0004,MRN-5510042,health-concern,44054006,http://snomed.info/sct,active,,,,2026-01-09,,, +CND-0005,MRN-3391077,sdoh,44054006,http://snomed.info/sct,active,,,,2026-03-02,,, diff --git a/assets/data-integration/coverage.csv b/assets/data-integration/coverage.csv index f63e816..063915d 100644 --- a/assets/data-integration/coverage.csv +++ b/assets/data-integration/coverage.csv @@ -1,4 +1,4 @@ -record_id,patient_identifier,status,member_id,subscriber_id,relationship_code,coverage_type_code,payer_org_npi,group_number,group_name,plan_number,plan_name,period_start,period_end,is_deleted -COV-0001,MRN-4471903,active,HSX9930012,HSX9930012,self,1,9999999993,GRP-4410,Acme Manufacturing,H6776-001,Gold PPO,2026-01-01,2026-12-31, -COV-0002,MRN-3391077,active,HSX9930013,HSX9930012,spouse,1,9999999993,,,,,2026-01-01,2026-12-31, -COV-0003,MRN-4471903,cancelled,HSX8820001,HSX8820001,self,,9999999993,,,,,2025-01-01,2025-12-31, +coverage_id,patient_identifier,status,member_id,subscriber_id,relationship_code,coverage_type_code,payer_org_npi,group_number,group_name,plan_number,plan_name,period_start,period_end,is_deleted +COV-0001,MRN-4471903,active,HSX9930012,HSX9930012,self,1,9999999993,GRP-4410,Acme Manufacturing,H6776-001,Gold PPO,2026-01-01,2026-12-31, +COV-0002,MRN-3391077,active,HSX9930013,HSX9930012,spouse,1,9999999993,,,,,2026-01-01,2026-12-31, +COV-0003,MRN-4471903,cancelled,HSX8820001,HSX8820001,self,,9999999993,,,,,2025-01-01,2025-12-31, diff --git a/assets/data-integration/devices.csv b/assets/data-integration/devices.csv index 30f3019..c6bc9e6 100644 --- a/assets/data-integration/devices.csv +++ b/assets/data-integration/devices.csv @@ -1,3 +1,3 @@ -record_id,patient_identifier,udi_device_identifier,udi_carrier_hrf,device_type_code,device_type_system,distinct_identifier,lot_number,serial_number,manufacture_date,expiration_date,is_deleted -DV-0001,MRN-4471903,00643169007222,(01)00643169007222(17)…,468063009,http://snomed.info/sct,456,543211,842026,2019-03-01,2029-03-01, -DV-0002,MRN-7782200,00643169007222,,468063009,http://snomed.info/sct,,,,,, +device_id,patient_identifier,udi_device_identifier,udi_carrier_hrf,device_type_code,device_type_system,distinct_identifier,lot_number,serial_number,manufacture_date,expiration_date,is_deleted +DV-0001,MRN-4471903,00643169007222,(01)00643169007222(17)…,468063009,http://snomed.info/sct,456,543211,842026,2019-03-01,2029-03-01, +DV-0002,MRN-7782200,00643169007222,,468063009,http://snomed.info/sct,,,,,, diff --git a/assets/data-integration/diagnostic_reports.csv b/assets/data-integration/diagnostic_reports.csv index af76e94..4e40238 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,,,,, +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,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/documents.csv b/assets/data-integration/documents.csv index 600ef44..3a18bb3 100644 --- a/assets/data-integration/documents.csv +++ b/assets/data-integration/documents.csv @@ -1,4 +1,4 @@ -record_id,patient_identifier,type_code,attachment_file,record_id,document_date,author_npi,encounter_id,is_deleted -DOC-0001,MRN-4471903,11488-4,attachments/DOC-0001.pdf,DOC-0001,2026-04-18T10:00:00-04:00,9999999991,ENC-9912, -DOC-0002,MRN-7782200,18842-5,attachments/DOC-0002.pdf,DOC-0002,2026-02-06T11:30:00-05:00,9999999991,ENC-9913, -DOC-0003,MRN-5510042,11506-3,attachments/DOC-0003.pdf,DOC-0003,2026-01-09T15:05:00-05:00,,, +document_id,patient_identifier,type_code,attachment_file,document_date,author_npi,encounter_id,is_deleted +DOC-0001,MRN-4471903,11488-4,attachments/DOC-0001.pdf,2026-04-18T10:00:00-04:00,9999999991,ENC-9912, +DOC-0002,MRN-7782200,18842-5,attachments/DOC-0002.pdf,2026-02-06T11:30:00-05:00,9999999991,ENC-9913, +DOC-0003,MRN-5510042,11506-3,attachments/DOC-0003.pdf,2026-01-09T15:05:00-05:00,,, diff --git a/assets/data-integration/encounters.csv b/assets/data-integration/encounters.csv index ba190f5..00c8b0c 100644 --- a/assets/data-integration/encounters.csv +++ b/assets/data-integration/encounters.csv @@ -1,5 +1,5 @@ -record_id,encounter_id,encounter_id_system,patient_identifier,status,class,type_code,type_system,period_start,period_end,reason_code,reason_system,location_id,diagnosis_condition_id,participant_npi,participant_type_code,participant_type_system,discharge_disposition_code,discharge_disposition_system,service_provider_npi,is_deleted -ENC-9912,ENC-9912,urn:oid:2.16.840.1.113883.3.99.2,MRN-4471903,finished,AMB,99213,,2026-04-18T09:00:00-04:00,2026-04-18T09:30:00-04:00,29857009,,LOC-221,,9999999991,ATND,,,,9999999993, -ENC-9913,ENC-9913,urn:oid:2.16.840.1.113883.3.99.2,MRN-7782200,finished,IMP,99213,,2026-02-01T14:00:00-05:00,2026-02-06T11:00:00-05:00,,,,CND-4501,9999999991,ADM,,01,http://www.nubc.org/patient-discharge,9999999993, -ENC-9914,ENC-9914,urn:oid:2.16.840.1.113883.3.99.2,MRN-3391077,finished,EMER,99213,,2026-05-20T22:10:00-04:00,2026-05-21T02:40:00-04:00,29857009,,,,,,,,,, -ENC-9915,ENC-9915,urn:oid:2.16.840.1.113883.3.99.2,MRN-5510042,cancelled,AMB,99213,,,,,,,,,,,,,, +encounter_id,encounter_id_system,patient_identifier,status,class,type_code,type_system,period_start,period_end,reason_code,reason_system,location_id,diagnosis_condition_id,participant_npi,participant_type_code,participant_type_system,discharge_disposition_code,discharge_disposition_system,service_provider_npi,is_deleted +ENC-9912,urn:oid:2.16.840.1.113883.3.99.2,MRN-4471903,finished,AMB,99213,,2026-04-18T09:00:00-04:00,2026-04-18T09:30:00-04:00,29857009,,LOC-221,,9999999991,ATND,,,,9999999993, +ENC-9913,urn:oid:2.16.840.1.113883.3.99.2,MRN-7782200,finished,IMP,99213,,2026-02-01T14:00:00-05:00,2026-02-06T11:00:00-05:00,,,,CND-4501,9999999991,ADM,,01,http://www.nubc.org/patient-discharge,9999999993, +ENC-9914,urn:oid:2.16.840.1.113883.3.99.2,MRN-3391077,finished,EMER,99213,,2026-05-20T22:10:00-04:00,2026-05-21T02:40:00-04:00,29857009,,,,,,,,,, +ENC-9915,urn:oid:2.16.840.1.113883.3.99.2,MRN-5510042,cancelled,AMB,99213,,,,,,,,,,,,,, diff --git a/assets/data-integration/goals.csv b/assets/data-integration/goals.csv index 516e7c8..b70d4ca 100644 --- 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,is_deleted -GL-0001,MRN-4471903,active,289169006,http://snomed.info/sct,2026-04-18,2026-10-18, -GL-0002,MRN-7782200,completed,289169006,http://snomed.info/sct,2025-03-01,2025-09-01, -GL-0003,MRN-5510042,proposed,289169006,http://snomed.info/sct,,, +goal_id,patient_identifier,lifecycle_status,description_code,description_system,start_date,target_date,is_deleted +GL-0001,MRN-4471903,active,289169006,http://snomed.info/sct,2026-04-18,2026-10-18, +GL-0002,MRN-7782200,completed,289169006,http://snomed.info/sct,2025-03-01,2025-09-01, +GL-0003,MRN-5510042,proposed,289169006,http://snomed.info/sct,,, diff --git a/assets/data-integration/immunizations.csv b/assets/data-integration/immunizations.csv index 92714ea..6ae4b29 100644 --- a/assets/data-integration/immunizations.csv +++ b/assets/data-integration/immunizations.csv @@ -1,4 +1,4 @@ -record_id,patient_identifier,status,status_reason_code,status_reason_system,vaccine_code,vaccine_system,occurrence_date,performer_npi,primary_source,is_deleted -IM-0001,MRN-4471903,completed,,,140,,2025-10-02,9999999991,true, -IM-0002,MRN-7782200,not-done,PATOBJ,http://terminology.hl7.org/CodeSystem/v3-ActReason,140,,2025-11-14,,, -IM-0003,MRN-5510042,completed,,,140,,2019-09-30,,false, +immunization_id,patient_identifier,status,status_reason_code,status_reason_system,vaccine_code,vaccine_system,occurrence_date,performer_npi,primary_source,is_deleted +IM-0001,MRN-4471903,completed,,,140,,2025-10-02,9999999991,true, +IM-0002,MRN-7782200,not-done,PATOBJ,http://terminology.hl7.org/CodeSystem/v3-ActReason,140,,2025-11-14,,, +IM-0003,MRN-5510042,completed,,,140,,2019-09-30,,false, diff --git a/assets/data-integration/locations.csv b/assets/data-integration/locations.csv index a6fd448..124dd00 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, +location_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/assets/data-integration/patients.csv b/assets/data-integration/patients.csv index b636214..9aa90e0 100644 --- 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,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,,, -PT-0002,MRN-5510042,http://example.org/mrns,,,,,,,,,,,Roe,John,,,,male,,,,,,,,,,,,,,,,,,,, -PT-0003,MRN-7782200,http://example.org/mrns,,,,,,,,,,,Poe,Ann,,,,female,,1940-02-29,2026-01-14,,,,,,,,,Anytown,NY,12345,,,,,, -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,,,,,, -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, +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,is_deleted +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,,, +MRN-5510042,http://example.org/mrns,,,,,,,,,,,Roe,John,,,,male,,,,,,,,,,,,,,,,,,,, +MRN-7782200,http://example.org/mrns,,,,,,,,,,,Poe,Ann,,,,female,,1940-02-29,2026-01-14,,,,,,,,,Anytown,NY,12345,,,,,, +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,,,,,, +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, diff --git a/assets/data-integration/practitioners.csv b/assets/data-integration/practitioners.csv index b80ff93..5e2c837 100644 --- 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,is_deleted -PRC-0001,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-221,5551234567,,2021-04-01,, -PRC-0002,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-884,5554445555,,,, -PRC-0003,9999999992,Fox,Dana,,,,,,,,, +practitioner_role_id,npi,last_name,first_name,specialty_nucc,primary_org_npi,practitioner_role_code,location_id,phone,email,role_period_start,role_period_end,is_deleted +PRC-0001,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-221,5551234567,,2021-04-01,, +PRC-0002,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-884,5554445555,,,, +PRC-0003,9999999992,Fox,Dana,,,,,,,,, diff --git a/assets/data-integration/procedures.csv b/assets/data-integration/procedures.csv index c5b80b7..c4b41e5 100644 --- a/assets/data-integration/procedures.csv +++ b/assets/data-integration/procedures.csv @@ -1,4 +1,4 @@ -record_id,patient_identifier,status,code,code_system,performed_start,performed_end,performer_npi,encounter_id,service_request_id,reason_code,reason_system,is_deleted -PRO-0001,MRN-4471903,completed,80146002,http://snomed.info/sct,2026-04-18,,9999999991,ENC-9912,,,, -PRO-0002,MRN-7782200,completed,80146002,http://snomed.info/sct,2026-02-02,2026-02-02,9999999991,ENC-9913,,,, -PRO-0003,MRN-3391077,completed,80146002,http://snomed.info/sct,2026-05-24,,,,SR-2201,733423003,, +procedure_id,patient_identifier,status,code,code_system,performed_start,performed_end,performer_npi,encounter_id,service_request_id,reason_code,reason_system,is_deleted +PRO-0001,MRN-4471903,completed,80146002,http://snomed.info/sct,2026-04-18,,9999999991,ENC-9912,,,, +PRO-0002,MRN-7782200,completed,80146002,http://snomed.info/sct,2026-02-02,2026-02-02,9999999991,ENC-9913,,,, +PRO-0003,MRN-3391077,completed,80146002,http://snomed.info/sct,2026-05-24,,,,SR-2201,733423003,, diff --git a/assets/data-integration/related_persons.csv b/assets/data-integration/related_persons.csv index 850d8ed..52620a1 100644 --- a/assets/data-integration/related_persons.csv +++ b/assets/data-integration/related_persons.csv @@ -1,5 +1,5 @@ -record_id,patient_identifier,relationship_code,last_name,first_name,phone,address_line1,city,state,zip,active,is_deleted -RP-3310,MRN-4471903,DAU,Doe,Mary,5559876543,45 Oak St,Anytown,NY,12345,true, -RP-0002,MRN-4471903,SPS,Doe,Robert,,,,,,true, -RP-0003,MRN-7782200,GUARD,Poe,Alan,5552223333,,,,,false, -RP-0004,MRN-3391077,CHILD,Fox,Lee,,,,,,true, +related_person_id,patient_identifier,relationship_code,last_name,first_name,phone,address_line1,city,state,zip,active,is_deleted +RP-3310,MRN-4471903,DAU,Doe,Mary,5559876543,45 Oak St,Anytown,NY,12345,true, +RP-0002,MRN-4471903,SPS,Doe,Robert,,,,,,true, +RP-0003,MRN-7782200,GUARD,Poe,Alan,5552223333,,,,,false, +RP-0004,MRN-3391077,CHILD,Fox,Lee,,,,,,true, diff --git a/assets/data-integration/service_requests.csv b/assets/data-integration/service_requests.csv index f56bee2..89e9f2f 100644 --- a/assets/data-integration/service_requests.csv +++ b/assets/data-integration/service_requests.csv @@ -1,4 +1,4 @@ -record_id,patient_identifier,status,intent,code,code_system,category,category_system,reason_code,reason_system,authored_on,occurrence_date,requester_npi,is_deleted -SR-2201,MRN-3391077,active,order,103696004,http://snomed.info/sct,sdoh,http://hl7.org/fhir/us/core/CodeSystem/us-core-category,733423003,,2026-05-10,2026-05-24,9999999991, -SR-0002,MRN-4471903,active,order,103696004,http://snomed.info/sct,,,,,2026-04-18,,9999999991, -SR-0003,MRN-7782200,completed,plan,103696004,http://snomed.info/sct,,,,,2025-12-01,,, +service_request_id,patient_identifier,status,intent,code,code_system,category,category_system,reason_code,reason_system,authored_on,occurrence_date,requester_npi,is_deleted +SR-2201,MRN-3391077,active,order,103696004,http://snomed.info/sct,sdoh,http://hl7.org/fhir/us/core/CodeSystem/us-core-category,733423003,,2026-05-10,2026-05-24,9999999991, +SR-0002,MRN-4471903,active,order,103696004,http://snomed.info/sct,,,,,2026-04-18,,9999999991, +SR-0003,MRN-7782200,completed,plan,103696004,http://snomed.info/sct,,,,,2025-12-01,,, diff --git a/assets/data-integration/social_history.csv b/assets/data-integration/social_history.csv index 9837887..17020b5 100644 --- a/assets/data-integration/social_history.csv +++ b/assets/data-integration/social_history.csv @@ -1,6 +1,6 @@ -record_id,patient_identifier,observation_type,status,value_code,value_system,industry_code,effective_datetime,is_deleted -SH-0001,MRN-4471903,occupation,final,29-1141.00,,622110,2026-04-18, -SH-0002,MRN-4471903,smoking-status,final,266919005,http://snomed.info/sct,,2026-04-18, -SH-0003,MRN-7782200,smoking-status,final,8517006,http://snomed.info/sct,,2026-02-11, -SH-0004,MRN-3391077,pregnancy-status,final,77386006,http://snomed.info/sct,,2026-03-02, -SH-0005,MRN-3391077,pregnancy-status,corrected,60001007,http://snomed.info/sct,,2026-05-20, +social_history_id,patient_identifier,observation_type,status,value_code,value_system,industry_code,effective_datetime,is_deleted +SH-0001,MRN-4471903,occupation,final,29-1141.00,,622110,2026-04-18, +SH-0002,MRN-4471903,smoking-status,final,266919005,http://snomed.info/sct,,2026-04-18, +SH-0003,MRN-7782200,smoking-status,final,8517006,http://snomed.info/sct,,2026-02-11, +SH-0004,MRN-3391077,pregnancy-status,final,77386006,http://snomed.info/sct,,2026-03-02, +SH-0005,MRN-3391077,pregnancy-status,corrected,60001007,http://snomed.info/sct,,2026-05-20, diff --git a/assets/data-integration/vital_signs.csv b/assets/data-integration/vital_signs.csv index 1cd04bc..b898467 100644 --- a/assets/data-integration/vital_signs.csv +++ b/assets/data-integration/vital_signs.csv @@ -1,6 +1,6 @@ -record_id,patient_identifier,status,loinc_code,effective_datetime,value,unit,component_systolic,component_diastolic,encounter_id,performer_npi,is_deleted -VS-0001,MRN-4471903,final,85354-9,2026-04-18T09:05:00-04:00,,,128,82,ENC-9912,9999999991, -VS-0002,MRN-4471903,final,8867-4,2026-04-18T09:05:00-04:00,72,/min,,,ENC-9912,, -VS-0003,MRN-4471903,final,8302-2,2026-04-18T09:05:00-04:00,163,cm,,,,, -VS-0004,MRN-4471903,final,29463-7,2026-04-18T09:05:00-04:00,64.5,kg,,,,, -VS-0005,MRN-7782200,final,8310-5,2026-02-02T21:40:00-05:00,38.2,Cel,,,ENC-9913,, +vital_sign_id,patient_identifier,status,loinc_code,effective_datetime,value,unit,component_systolic,component_diastolic,encounter_id,performer_npi,is_deleted +VS-0001,MRN-4471903,final,85354-9,2026-04-18T09:05:00-04:00,,,128,82,ENC-9912,9999999991, +VS-0002,MRN-4471903,final,8867-4,2026-04-18T09:05:00-04:00,72,/min,,,ENC-9912,, +VS-0003,MRN-4471903,final,8302-2,2026-04-18T09:05:00-04:00,163,cm,,,,, +VS-0004,MRN-4471903,final,29463-7,2026-04-18T09:05:00-04:00,64.5,kg,,,,, +VS-0005,MRN-7782200,final,8310-5,2026-02-02T21:40:00-05:00,38.2,Cel,,,ENC-9913,, diff --git a/docs/data-integration/README.md b/docs/data-integration/README.md index 682b7a6..8d6146c 100644 --- a/docs/data-integration/README.md +++ b/docs/data-integration/README.md @@ -23,7 +23,7 @@ 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. | +| Keys (USCDI feed) | Each dataset names its own key column, listed first in its table. Payerbox derives the resource id from it, so keep it stable across deliveries: the same value updates the row in place, a new one creates a second resource. `is_deleted` set to `true` retracts the row it names. | | 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/allergies.md b/docs/data-integration/uscdi/allergies.md index 7f3d082..5ba4263 100644 --- a/docs/data-integration/uscdi/allergies.md +++ b/docs/data-integration/uscdi/allergies.md @@ -24,6 +24,7 @@ allergies.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `allergy_id` | Yes | your key for this allergy | `AL-0001` | | `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 | | `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%7C4.0.1) | `active` | diff --git a/docs/data-integration/uscdi/care-plans.md b/docs/data-integration/uscdi/care-plans.md index 4bd9351..f3eaf8b 100644 --- a/docs/data-integration/uscdi/care-plans.md +++ b/docs/data-integration/uscdi/care-plans.md @@ -24,6 +24,7 @@ care_plans.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `care_plan_id` | Yes | your key for this care plan | `CP-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `narrative_text` | Yes | text or HTML; the assessment and plan itself | `Assessment: … Plan: …` | | `status` | Yes | `draft`, `active`, `on-hold`, `revoked`, `completed`, `entered-in-error`, `unknown` [request-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/request-status%7C4.0.1) | `active` | diff --git a/docs/data-integration/uscdi/care-team.md b/docs/data-integration/uscdi/care-team.md index 09cd080..ed13dda 100644 --- a/docs/data-integration/uscdi/care-team.md +++ b/docs/data-integration/uscdi/care-team.md @@ -27,6 +27,7 @@ practitioners.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `practitioner_role_id` | Yes | your key for this practitioner-at-location row; `care_team` and `encounters` reference the `npi` | `PRC-0001` | | `npi` | Yes | 10 digits | `9999999991` | | `last_name` | Yes | text | `Roe` | | `first_name` | Recommended | text | `Richard` | @@ -49,9 +50,10 @@ care_team.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `care_team_id` | Yes | your key for this care team row | `CT-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `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` | +| `member_related_person_id` | Yes, unless `member_npi` is sent | `related_person_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` | diff --git a/docs/data-integration/uscdi/clinical-notes.md b/docs/data-integration/uscdi/clinical-notes.md index 1750f58..147143d 100644 --- a/docs/data-integration/uscdi/clinical-notes.md +++ b/docs/data-integration/uscdi/clinical-notes.md @@ -39,16 +39,15 @@ documents.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `document_id` | Yes | your key for this note | `DOC-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `type_code` | Yes | LOINC note type, e.g. `11488-4` consult, `18842-5` discharge summary, `34117-2` history and physical, `11506-3` progress note [US Core DocumentReference Type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-documentreference-type) | `11488-4` | | `attachment_file` | Yes | path relative to the delivery root | `attachments/DOC-0001.pdf` | -| `record_id` | Recommended | your stable row key | `DOC-0001` | | `document_date` | Recommended | datetime | `2026-04-18T10:00:00-04:00` | | `author_npi` | Recommended | 10 digits | `9999999991` | | `encounter_id` | If applicable | `encounters` key | `ENC-9912` | - `type_code` has a required binding, so the note type must come from that value set. It is large, but the four codes above cover most of what a payer holds. -- `record_id` is the upsert key. It is optional on this dataset alone, defaulting to `attachment_file` — so send it if your filenames change between exports, or a renamed file becomes a second note. - Payerbox sets the status to `current` and the category to `clinical-note`, and reads the attachment's content type and size from the stored file. None of those are columns. ## diagnostic_reports @@ -61,7 +60,7 @@ 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` | +| `report_id` | Yes | your key for this report; result rows reference it | `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..056fbf0 100644 --- a/docs/data-integration/uscdi/clinical-tests.md +++ b/docs/data-integration/uscdi/clinical-tests.md @@ -24,6 +24,7 @@ clinical_observations.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `observation_id` | Yes | your key for this observation; panel members reference it | `CO-1200` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `category` | Yes | one of the [categories](#categories) below | `sdoh` | | `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%7C4.0.1) | `final` | @@ -35,7 +36,7 @@ clinical_observations.csv Data template with example rows | `data_absent_reason` | If there is no result | `unknown`, `asked-declined`, `not-performed` [data-absent-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/data-absent-reason%7C4.0.1) | | | `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` | +| `panel_id` | If available | `observation_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. diff --git a/docs/data-integration/uscdi/conditions.md b/docs/data-integration/uscdi/conditions.md index f7b910a..a6a66c6 100644 --- a/docs/data-integration/uscdi/conditions.md +++ b/docs/data-integration/uscdi/conditions.md @@ -24,6 +24,7 @@ conditions.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `condition_id` | Yes | your key for this condition; `encounters` reference it | `CND-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `category` | Yes | one of seven values — see [Categories](#categories) | `problem-list-item` | | `code` | Yes | SNOMED CT or ICD-10-CM code, with `code_system` [us-core-condition-code](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-condition-code) | `44054006` Type 2 diabetes mellitus | diff --git a/docs/data-integration/uscdi/devices.md b/docs/data-integration/uscdi/devices.md index dd8647b..ecfd54e 100644 --- a/docs/data-integration/uscdi/devices.md +++ b/docs/data-integration/uscdi/devices.md @@ -24,6 +24,7 @@ devices.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `device_id` | Yes | your key for this device row | `DV-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `udi_device_identifier` | Yes | DI portion of the UDI | `00643169007222` | | `udi_carrier_hrf` | Recommended | full UDI barcode string, human-readable form | `(01)00643169007222(17)…` | diff --git a/docs/data-integration/uscdi/encounters.md b/docs/data-integration/uscdi/encounters.md index cd457f9..ac7d38c 100644 --- a/docs/data-integration/uscdi/encounters.md +++ b/docs/data-integration/uscdi/encounters.md @@ -25,7 +25,7 @@ encounters.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| -| `encounter_id` | Yes | stable encounter key; the key other datasets reference | `ENC-9912` | +| `encounter_id` | Yes | your key for this encounter; other datasets reference it | `ENC-9912` | | `encounter_id_system` | Yes | URI of the identifier system; a URL you control or an OID | `urn:oid:2.16.840.1.113883.3.99.2` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `status` | Yes | `planned`, `arrived`, `triaged`, `in-progress`, `onleave`, `finished`, `cancelled`, `entered-in-error`, `unknown` [encounter-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/encounter-status%7C4.0.1) | `finished` | @@ -35,7 +35,7 @@ encounters.csv Data template with example rows | `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` | -| `diagnosis_condition_id` | If available | `record_id` of the `conditions` row(s), `;`-separated | `CND-4501` | +| `diagnosis_condition_id` | If available | `condition_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` | | `discharge_disposition_code` | If applicable | NUBC patient discharge status code, as carried in UB-04 field 17, with `discharge_disposition_system` [AHA NUBC Patient Discharge Status](https://terminology.hl7.org/5.5.0/CodeSystem-AHANUBCPatientDischargeStatus.html) | `01` discharged to home or self-care | @@ -57,7 +57,7 @@ locations.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| -| `location_id` | Yes | stable id; the key `encounters` references | `LOC-221` | +| `location_id` | Yes | your key for this location; `encounters` and `practitioners` reference it | `LOC-221` | | `location_name` | Yes | text | `Anytown Family Practice` | | `managing_org_npi` | Recommended | 10 digits | `9999999993` | | `address_line1` | Recommended | text | `123 Main St` | diff --git a/docs/data-integration/uscdi/goals.md b/docs/data-integration/uscdi/goals.md index 3032a9c..7012bb3 100644 --- a/docs/data-integration/uscdi/goals.md +++ b/docs/data-integration/uscdi/goals.md @@ -24,6 +24,7 @@ goals.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `goal_id` | Yes | your key for this goal | `GL-0001` | | `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) | `289169006` exercising to lose weight | diff --git a/docs/data-integration/uscdi/health-insurance.md b/docs/data-integration/uscdi/health-insurance.md index 0dee938..7d19bf0 100644 --- a/docs/data-integration/uscdi/health-insurance.md +++ b/docs/data-integration/uscdi/health-insurance.md @@ -24,6 +24,7 @@ coverage.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `coverage_id` | Yes | your key for this coverage | `COV-0001` | | `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` | Yes, unless `subscriber_id` is sent | plan member id | `HSX9930012` | diff --git a/docs/data-integration/uscdi/immunizations.md b/docs/data-integration/uscdi/immunizations.md index 119e75b..b22a970 100644 --- a/docs/data-integration/uscdi/immunizations.md +++ b/docs/data-integration/uscdi/immunizations.md @@ -26,6 +26,7 @@ immunizations.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `immunization_id` | Yes | your key for this dose | `IM-0001` | | `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%7C4.0.1) | `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%7C4.0.1) | `PATOBJ` patient objection | diff --git a/docs/data-integration/uscdi/patient-demographics.md b/docs/data-integration/uscdi/patient-demographics.md index b46ed99..6594597 100644 --- a/docs/data-integration/uscdi/patient-demographics.md +++ b/docs/data-integration/uscdi/patient-demographics.md @@ -99,6 +99,7 @@ related_persons.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `related_person_id` | Yes | your key for this person; `care_team` references it | `RP-3310` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `relationship_code` | Recommended | `DAU` daughter, `SPS` spouse, `CHILD` child [v3-RoleCode](https://terminology.hl7.org/CodeSystem-v3-RoleCode.html), [v2-0131](https://terminology.hl7.org/CodeSystem-v2-0131.html) | `DAU` | | `last_name` | Recommended | text | `Doe` | @@ -118,6 +119,7 @@ social_history.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `social_history_id` | Yes | your key for this row | `SH-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `observation_type` | Yes | `occupation` for the demographics rows; `smoking-status`, `pregnancy-status`, `pregnancy-intent` are Health Status/Assessments | `occupation` | | `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%7C4.0.1) | `final` | diff --git a/docs/data-integration/uscdi/procedures.md b/docs/data-integration/uscdi/procedures.md index b13a1c3..5df07e7 100644 --- a/docs/data-integration/uscdi/procedures.md +++ b/docs/data-integration/uscdi/procedures.md @@ -25,6 +25,7 @@ procedures.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `procedure_id` | Yes | your key for this procedure | `PRO-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `status` | Yes | `preparation`, `in-progress`, `on-hold`, `stopped`, `completed`, `not-done`, `entered-in-error`, `unknown` [event-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/event-status%7C4.0.1) | `completed` | | `code` | Yes | CPT, HCPCS, ICD-10-PCS, or SNOMED CT code, with `code_system`; CPT if omitted [US Core Procedure Codes](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-procedure-code) | `80146002` appendectomy | @@ -32,7 +33,7 @@ procedures.csv Data template with example rows | `performed_end` | If a period | date or datetime | | | `performer_npi` | If available | 10 digits | `9999999991` | | `encounter_id` | If applicable | `encounters` key | `ENC-9912` | -| `service_request_id` | If available | `record_id` of the `service_requests` row, when the procedure fulfils a request | `SR-2201` | +| `service_request_id` | If available | `service_request_id` of the `service_requests` row, when the procedure fulfils a request | `SR-2201` | | `reason_code` | If available | SNOMED CT or ICD-10-CM code(s), `;`-separated, with `reason_system`; SNOMED CT if omitted [procedure-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/procedure-reason%7C4.0.1) | `733423003` food insecurity | - `performed_end` marks a procedure that spans time. Send it only then; a single `performed_start` is a point in time. @@ -48,6 +49,7 @@ service_requests.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `service_request_id` | Yes | your key for this request; `procedures` reference it | `SR-2201` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `status` | Yes | `draft`, `active`, `on-hold`, `completed`, `revoked`, `entered-in-error`, `unknown` [request-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/request-status%7C4.0.1) | `active` | | `intent` | Yes | `proposal`, `plan`, `directive`, `order`, `original-order`, `reflex-order`, `filler-order`, `instance-order`, `option` [request-intent](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/request-intent%7C4.0.1) | `order` | diff --git a/docs/data-integration/uscdi/vital-signs.md b/docs/data-integration/uscdi/vital-signs.md index da06b95..0b18387 100644 --- a/docs/data-integration/uscdi/vital-signs.md +++ b/docs/data-integration/uscdi/vital-signs.md @@ -24,6 +24,7 @@ vital_signs.csv Data template with example rows | Column | Required | Format / values | Example | |---|---|---|---| +| `vital_sign_id` | Yes | your key for this reading | `VS-0001` | | `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%7C4.0.1) | `final` | | `loinc_code` | Yes | one of the [vital sign codes](#vital-sign-codes) below [US Core Vital Signs](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-vital-signs) | `8867-4` | From c9da8d0ab4d0cd47461dafdf1e93593c3d233cdf Mon Sep 17 00:00:00 2001 From: Akim Khalitov Date: Thu, 27 Aug 2026 22:18:54 +0400 Subject: [PATCH 2/3] docs(data-integration): fingerprint the templates so edits reach readers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The site serves assets/** with `cache-control: max-age=31536000, immutable` while the pages get max-age=60, so an edited template never reaches anyone: the edge froze the pre-16:12 CSVs and would have served them until 2027. A query string does not help, since it is not part of the cache key. That header is right for content-addressed files and wrong for permanent ones, so the filenames now carry the content hash — new content, new URL, fresh fetch. The file widget keeps the URL and the label on separate lines, so a reader still sees clinical_observations.csv. `bun assets:hash` recomputes them; run it after touching a template. --- .../{allergies.csv => allergies.4a0f3db1.csv} | 0 ...care_plans.csv => care_plans.a7a2d06d.csv} | 0 .../{care_team.csv => care_team.50c89a77.csv} | 0 ...csv => clinical_observations.9984386b.csv} | 0 ...conditions.csv => conditions.eb153b88.csv} | 0 .../{coverage.csv => coverage.4d9e6894.csv} | 0 .../{devices.csv => devices.2ac2aa78.csv} | 0 ...ts.csv => diagnostic_reports.f5a3daa0.csv} | 0 .../{documents.csv => documents.4c460535.csv} | 0 ...encounters.csv => encounters.aaaeceb4.csv} | 0 .../{goals.csv => goals.7ce937f2.csv} | 0 ...zations.csv => immunizations.908bf32d.csv} | 0 .../{locations.csv => locations.8fd5cc92.csv} | 0 .../{patients.csv => patients.4d87f019.csv} | 0 ...tioners.csv => practitioners.961c4aea.csv} | 0 ...procedures.csv => procedures.ab0fa51c.csv} | 0 ...rsons.csv => related_persons.9ea0a20e.csv} | 0 ...ests.csv => service_requests.134c537d.csv} | 0 ...istory.csv => social_history.d2f5c741.csv} | 0 ...tal_signs.csv => vital_signs.a2c1821b.csv} | 0 docs/data-integration/uscdi/allergies.md | 2 +- docs/data-integration/uscdi/care-plans.md | 2 +- docs/data-integration/uscdi/care-team.md | 4 +- docs/data-integration/uscdi/clinical-notes.md | 4 +- docs/data-integration/uscdi/clinical-tests.md | 2 +- docs/data-integration/uscdi/conditions.md | 2 +- docs/data-integration/uscdi/devices.md | 2 +- docs/data-integration/uscdi/encounters.md | 4 +- docs/data-integration/uscdi/goals.md | 2 +- .../uscdi/health-insurance.md | 2 +- docs/data-integration/uscdi/immunizations.md | 2 +- .../uscdi/patient-demographics.md | 6 +- docs/data-integration/uscdi/procedures.md | 4 +- docs/data-integration/uscdi/vital-signs.md | 2 +- package.json | 1 + scripts/hash-assets.ts | 62 +++++++++++++++++++ 36 files changed, 83 insertions(+), 20 deletions(-) rename assets/data-integration/{allergies.csv => allergies.4a0f3db1.csv} (100%) rename assets/data-integration/{care_plans.csv => care_plans.a7a2d06d.csv} (100%) rename assets/data-integration/{care_team.csv => care_team.50c89a77.csv} (100%) rename assets/data-integration/{clinical_observations.csv => clinical_observations.9984386b.csv} (100%) rename assets/data-integration/{conditions.csv => conditions.eb153b88.csv} (100%) rename assets/data-integration/{coverage.csv => coverage.4d9e6894.csv} (100%) rename assets/data-integration/{devices.csv => devices.2ac2aa78.csv} (100%) rename assets/data-integration/{diagnostic_reports.csv => diagnostic_reports.f5a3daa0.csv} (100%) rename assets/data-integration/{documents.csv => documents.4c460535.csv} (100%) rename assets/data-integration/{encounters.csv => encounters.aaaeceb4.csv} (100%) rename assets/data-integration/{goals.csv => goals.7ce937f2.csv} (100%) rename assets/data-integration/{immunizations.csv => immunizations.908bf32d.csv} (100%) rename assets/data-integration/{locations.csv => locations.8fd5cc92.csv} (100%) rename assets/data-integration/{patients.csv => patients.4d87f019.csv} (100%) rename assets/data-integration/{practitioners.csv => practitioners.961c4aea.csv} (100%) rename assets/data-integration/{procedures.csv => procedures.ab0fa51c.csv} (100%) rename assets/data-integration/{related_persons.csv => related_persons.9ea0a20e.csv} (100%) rename assets/data-integration/{service_requests.csv => service_requests.134c537d.csv} (100%) rename assets/data-integration/{social_history.csv => social_history.d2f5c741.csv} (100%) rename assets/data-integration/{vital_signs.csv => vital_signs.a2c1821b.csv} (100%) create mode 100644 scripts/hash-assets.ts diff --git a/assets/data-integration/allergies.csv b/assets/data-integration/allergies.4a0f3db1.csv similarity index 100% rename from assets/data-integration/allergies.csv rename to assets/data-integration/allergies.4a0f3db1.csv diff --git a/assets/data-integration/care_plans.csv b/assets/data-integration/care_plans.a7a2d06d.csv similarity index 100% rename from assets/data-integration/care_plans.csv rename to assets/data-integration/care_plans.a7a2d06d.csv diff --git a/assets/data-integration/care_team.csv b/assets/data-integration/care_team.50c89a77.csv similarity index 100% rename from assets/data-integration/care_team.csv rename to assets/data-integration/care_team.50c89a77.csv diff --git a/assets/data-integration/clinical_observations.csv b/assets/data-integration/clinical_observations.9984386b.csv similarity index 100% rename from assets/data-integration/clinical_observations.csv rename to assets/data-integration/clinical_observations.9984386b.csv diff --git a/assets/data-integration/conditions.csv b/assets/data-integration/conditions.eb153b88.csv similarity index 100% rename from assets/data-integration/conditions.csv rename to assets/data-integration/conditions.eb153b88.csv diff --git a/assets/data-integration/coverage.csv b/assets/data-integration/coverage.4d9e6894.csv similarity index 100% rename from assets/data-integration/coverage.csv rename to assets/data-integration/coverage.4d9e6894.csv diff --git a/assets/data-integration/devices.csv b/assets/data-integration/devices.2ac2aa78.csv similarity index 100% rename from assets/data-integration/devices.csv rename to assets/data-integration/devices.2ac2aa78.csv diff --git a/assets/data-integration/diagnostic_reports.csv b/assets/data-integration/diagnostic_reports.f5a3daa0.csv similarity index 100% rename from assets/data-integration/diagnostic_reports.csv rename to assets/data-integration/diagnostic_reports.f5a3daa0.csv diff --git a/assets/data-integration/documents.csv b/assets/data-integration/documents.4c460535.csv similarity index 100% rename from assets/data-integration/documents.csv rename to assets/data-integration/documents.4c460535.csv diff --git a/assets/data-integration/encounters.csv b/assets/data-integration/encounters.aaaeceb4.csv similarity index 100% rename from assets/data-integration/encounters.csv rename to assets/data-integration/encounters.aaaeceb4.csv diff --git a/assets/data-integration/goals.csv b/assets/data-integration/goals.7ce937f2.csv similarity index 100% rename from assets/data-integration/goals.csv rename to assets/data-integration/goals.7ce937f2.csv diff --git a/assets/data-integration/immunizations.csv b/assets/data-integration/immunizations.908bf32d.csv similarity index 100% rename from assets/data-integration/immunizations.csv rename to assets/data-integration/immunizations.908bf32d.csv diff --git a/assets/data-integration/locations.csv b/assets/data-integration/locations.8fd5cc92.csv similarity index 100% rename from assets/data-integration/locations.csv rename to assets/data-integration/locations.8fd5cc92.csv diff --git a/assets/data-integration/patients.csv b/assets/data-integration/patients.4d87f019.csv similarity index 100% rename from assets/data-integration/patients.csv rename to assets/data-integration/patients.4d87f019.csv diff --git a/assets/data-integration/practitioners.csv b/assets/data-integration/practitioners.961c4aea.csv similarity index 100% rename from assets/data-integration/practitioners.csv rename to assets/data-integration/practitioners.961c4aea.csv diff --git a/assets/data-integration/procedures.csv b/assets/data-integration/procedures.ab0fa51c.csv similarity index 100% rename from assets/data-integration/procedures.csv rename to assets/data-integration/procedures.ab0fa51c.csv diff --git a/assets/data-integration/related_persons.csv b/assets/data-integration/related_persons.9ea0a20e.csv similarity index 100% rename from assets/data-integration/related_persons.csv rename to assets/data-integration/related_persons.9ea0a20e.csv diff --git a/assets/data-integration/service_requests.csv b/assets/data-integration/service_requests.134c537d.csv similarity index 100% rename from assets/data-integration/service_requests.csv rename to assets/data-integration/service_requests.134c537d.csv diff --git a/assets/data-integration/social_history.csv b/assets/data-integration/social_history.d2f5c741.csv similarity index 100% rename from assets/data-integration/social_history.csv rename to assets/data-integration/social_history.d2f5c741.csv diff --git a/assets/data-integration/vital_signs.csv b/assets/data-integration/vital_signs.a2c1821b.csv similarity index 100% rename from assets/data-integration/vital_signs.csv rename to assets/data-integration/vital_signs.a2c1821b.csv diff --git a/docs/data-integration/uscdi/allergies.md b/docs/data-integration/uscdi/allergies.md index 5ba4263..64647bd 100644 --- a/docs/data-integration/uscdi/allergies.md +++ b/docs/data-integration/uscdi/allergies.md @@ -18,7 +18,7 @@ description: >- One row per substance per patient. A substance with several reaction manifestations stays one row: list the manifestation codes `;`-separated. -{% file src="../../assets/data-integration/allergies.csv" %} +{% file src="../../assets/data-integration/allergies.4a0f3db1.csv" %} allergies.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/care-plans.md b/docs/data-integration/uscdi/care-plans.md index f3eaf8b..77ba5ea 100644 --- a/docs/data-integration/uscdi/care-plans.md +++ b/docs/data-integration/uscdi/care-plans.md @@ -18,7 +18,7 @@ description: >- One row per care plan. This dataset carries the **Assessment and Plan of Treatment** narrative; the SDOH Assessment element of the same class comes from `clinical_observations`. -{% file src="../../assets/data-integration/care_plans.csv" %} +{% file src="../../assets/data-integration/care_plans.a7a2d06d.csv" %} care_plans.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/care-team.md b/docs/data-integration/uscdi/care-team.md index ed13dda..78f10af 100644 --- a/docs/data-integration/uscdi/care-team.md +++ b/docs/data-integration/uscdi/care-team.md @@ -21,7 +21,7 @@ One row per practitioner, organization, and location: each row becomes one Pract If you already send the [Provider Directory](../provider-directory/README.md) feed, list here only the clinicians missing from it, such as an external ordering physician. -{% file src="../../assets/data-integration/practitioners.csv" %} +{% file src="../../assets/data-integration/practitioners.961c4aea.csv" %} practitioners.csv Data template with example rows {% endfile %} @@ -44,7 +44,7 @@ practitioners.csv Data template with example rows One row per patient and team member. -{% file src="../../assets/data-integration/care_team.csv" %} +{% file src="../../assets/data-integration/care_team.50c89a77.csv" %} care_team.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/clinical-notes.md b/docs/data-integration/uscdi/clinical-notes.md index 147143d..af333ca 100644 --- a/docs/data-integration/uscdi/clinical-notes.md +++ b/docs/data-integration/uscdi/clinical-notes.md @@ -33,7 +33,7 @@ delivery-2026-08-19/ One row per note. The note itself is the file; this row is its index card. -{% file src="../../assets/data-integration/documents.csv" %} +{% file src="../../assets/data-integration/documents.4c460535.csv" %} documents.csv Data template with example rows {% endfile %} @@ -54,7 +54,7 @@ documents.csv Data template with example rows One row per report. The individual results live in `labs` and `clinical_observations` and point back with `diagnostic_report_id`. -{% file src="../../assets/data-integration/diagnostic_reports.csv" %} +{% file src="../../assets/data-integration/diagnostic_reports.f5a3daa0.csv" %} diagnostic_reports.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/clinical-tests.md b/docs/data-integration/uscdi/clinical-tests.md index 056fbf0..a8d0ea9 100644 --- a/docs/data-integration/uscdi/clinical-tests.md +++ b/docs/data-integration/uscdi/clinical-tests.md @@ -18,7 +18,7 @@ description: >- One row per observation. This dataset carries every USCDI observation that is not a lab result, a vital sign or a social history row: non-lab test results, imaging findings, functional, disability and cognitive status, and SDOH screening answers. -{% file src="../../assets/data-integration/clinical_observations.csv" %} +{% file src="../../assets/data-integration/clinical_observations.9984386b.csv" %} clinical_observations.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/conditions.md b/docs/data-integration/uscdi/conditions.md index a6a66c6..88ead72 100644 --- a/docs/data-integration/uscdi/conditions.md +++ b/docs/data-integration/uscdi/conditions.md @@ -18,7 +18,7 @@ description: >- One file covers all four USCDI condition flavours — problems, health concerns, encounter diagnoses, and SDOH — one row per condition per patient; the `category` column tells them apart. -{% file src="../../assets/data-integration/conditions.csv" %} +{% file src="../../assets/data-integration/conditions.eb153b88.csv" %} conditions.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/devices.md b/docs/data-integration/uscdi/devices.md index ecfd54e..23c98c3 100644 --- a/docs/data-integration/uscdi/devices.md +++ b/docs/data-integration/uscdi/devices.md @@ -18,7 +18,7 @@ description: >- One row per implanted device per patient. The USCDI data class covers implantable devices only — other equipment does not belong in this file. -{% file src="../../assets/data-integration/devices.csv" %} +{% file src="../../assets/data-integration/devices.2ac2aa78.csv" %} devices.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/encounters.md b/docs/data-integration/uscdi/encounters.md index ac7d38c..62440f3 100644 --- a/docs/data-integration/uscdi/encounters.md +++ b/docs/data-integration/uscdi/encounters.md @@ -19,7 +19,7 @@ description: >- One row per encounter. Several diagnoses or participants stay one row: list the keys `;`-separated. -{% file src="../../assets/data-integration/encounters.csv" %} +{% file src="../../assets/data-integration/encounters.aaaeceb4.csv" %} encounters.csv Data template with example rows {% endfile %} @@ -51,7 +51,7 @@ One row per physical location: a clinic, a hospital ward, a lab draw station. If you already send the [Provider Directory](../provider-directory/README.md) feed, list here only the locations missing from it, such as a facility outside your network where a member was treated. -{% file src="../../assets/data-integration/locations.csv" %} +{% file src="../../assets/data-integration/locations.8fd5cc92.csv" %} locations.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/goals.md b/docs/data-integration/uscdi/goals.md index 7012bb3..a61920e 100644 --- a/docs/data-integration/uscdi/goals.md +++ b/docs/data-integration/uscdi/goals.md @@ -18,7 +18,7 @@ description: >- One row per goal per patient. -{% file src="../../assets/data-integration/goals.csv" %} +{% file src="../../assets/data-integration/goals.7ce937f2.csv" %} goals.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/health-insurance.md b/docs/data-integration/uscdi/health-insurance.md index 7d19bf0..776eb31 100644 --- a/docs/data-integration/uscdi/health-insurance.md +++ b/docs/data-integration/uscdi/health-insurance.md @@ -18,7 +18,7 @@ description: >- One row per coverage. A member with more than one plan, or a plan year that changed mid-year, produces more than one row. -{% file src="../../assets/data-integration/coverage.csv" %} +{% file src="../../assets/data-integration/coverage.4d9e6894.csv" %} coverage.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/immunizations.md b/docs/data-integration/uscdi/immunizations.md index b22a970..620341c 100644 --- a/docs/data-integration/uscdi/immunizations.md +++ b/docs/data-integration/uscdi/immunizations.md @@ -20,7 +20,7 @@ description: >- One row per administered (or refused) dose per patient. A member with three seasonal flu shots is three rows. -{% file src="../../assets/data-integration/immunizations.csv" %} +{% file src="../../assets/data-integration/immunizations.908bf32d.csv" %} immunizations.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/patient-demographics.md b/docs/data-integration/uscdi/patient-demographics.md index 6594597..e57dfee 100644 --- a/docs/data-integration/uscdi/patient-demographics.md +++ b/docs/data-integration/uscdi/patient-demographics.md @@ -20,7 +20,7 @@ description: >- One row per member. The sections below group its columns. -{% file src="../../assets/data-integration/patients.csv" %} +{% file src="../../assets/data-integration/patients.4d87f019.csv" %} patients.csv Data template with example rows {% endfile %} @@ -93,7 +93,7 @@ patients.csv Data template with example rows Contacts and non-clinician care-team members, such as a daughter, spouse, or guardian. One row per person per patient. -{% file src="../../assets/data-integration/related_persons.csv" %} +{% file src="../../assets/data-integration/related_persons.9ea0a20e.csv" %} related_persons.csv Data template with example rows {% endfile %} @@ -113,7 +113,7 @@ related_persons.csv Data template with example rows ## social_history -{% file src="../../assets/data-integration/social_history.csv" %} +{% file src="../../assets/data-integration/social_history.d2f5c741.csv" %} social_history.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/procedures.md b/docs/data-integration/uscdi/procedures.md index 5df07e7..9e73f77 100644 --- a/docs/data-integration/uscdi/procedures.md +++ b/docs/data-integration/uscdi/procedures.md @@ -19,7 +19,7 @@ description: >- One row per procedure performed. This dataset carries the **Procedures** element of the class. -{% file src="../../assets/data-integration/procedures.csv" %} +{% file src="../../assets/data-integration/procedures.ab0fa51c.csv" %} procedures.csv Data template with example rows {% endfile %} @@ -43,7 +43,7 @@ procedures.csv Data template with example rows One row per requested service: a referral, an order, or an SDOH intervention. This dataset carries the **Reason for Referral** and **SDOH Interventions** elements of the class; the services actually performed go in `procedures`. -{% file src="../../assets/data-integration/service_requests.csv" %} +{% file src="../../assets/data-integration/service_requests.134c537d.csv" %} service_requests.csv Data template with example rows {% endfile %} diff --git a/docs/data-integration/uscdi/vital-signs.md b/docs/data-integration/uscdi/vital-signs.md index 0b18387..d5e645b 100644 --- a/docs/data-integration/uscdi/vital-signs.md +++ b/docs/data-integration/uscdi/vital-signs.md @@ -18,7 +18,7 @@ description: >- One row per measurement, except blood pressure: systolic and diastolic are two components of a single reading, so they share a row. -{% file src="../../assets/data-integration/vital_signs.csv" %} +{% file src="../../assets/data-integration/vital_signs.a2c1821b.csv" %} vital_signs.csv Data template with example rows {% endfile %} diff --git a/package.json b/package.json index 6ec09a7..e90d1da 100644 --- a/package.json +++ b/package.json @@ -6,6 +6,7 @@ "lint": "docs-lint", "lint:check": "docs-lint --check", "lint:json": "docs-lint --json", + "assets:hash": "bun scripts/hash-assets.ts", "images:check": "docs-images check", "images:optimize": "docs-images optimize", "images:dry-run": "docs-images optimize --dry-run" diff --git a/scripts/hash-assets.ts b/scripts/hash-assets.ts new file mode 100644 index 0000000..fe6899b --- /dev/null +++ b/scripts/hash-assets.ts @@ -0,0 +1,62 @@ +#!/usr/bin/env bun +// +// Fingerprints the data-integration templates. +// +// The site serves assets/** with `cache-control: max-age=31536000, immutable`, +// so an edited template never reaches anyone at its old URL. Putting the content +// hash in the filename is what that header expects: new content, new URL, fresh +// fetch. The file widget's visible label is a separate line, so readers still +// see `clinical_observations.csv`. +// +// Run after touching a template: bun assets:hash + +import { createHash } from "node:crypto"; +import { readdir, readFile, rename, writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +const ASSETS = "assets/data-integration"; +const DOCS = "docs"; +const NAME = /^(.+?)(?:\.[0-9a-f]{8})?\.csv$/; + +async function markdownFiles(dir: string): Promise { + const out: string[] = []; + for (const entry of await readdir(dir, { withFileTypes: true })) { + const path = join(dir, entry.name); + if (entry.isDirectory()) out.push(...(await markdownFiles(path))); + else if (entry.name.endsWith(".md")) out.push(path); + } + return out; +} + +const renames = new Map(); // base name -> hashed file name + +for (const entry of (await readdir(ASSETS)).sort()) { + const match = NAME.exec(entry); + if (!match) continue; + + const base = match[1]; + const body = await readFile(join(ASSETS, entry)); + const hash = createHash("sha256").update(body).digest("hex").slice(0, 8); + const hashed = `${base}.${hash}.csv`; + + if (entry !== hashed) { + await rename(join(ASSETS, entry), join(ASSETS, hashed)); + console.log(` ${entry} -> ${hashed}`); + } + renames.set(base, hashed); +} + +for (const path of await markdownFiles(DOCS)) { + const before = await readFile(path, "utf8"); + let after = before; + + for (const [base, hashed] of renames) { + const pattern = new RegExp(`(${ASSETS}/)${base}(?:\\.[0-9a-f]{8})?\\.csv`, "g"); + after = after.replace(pattern, `$1${hashed}`); + } + + if (after !== before) { + await writeFile(path, after); + console.log(` updated ${path}`); + } +} From f8731cb0e71e020c3aa8dfefde4b4011734a7280 Mon Sep 17 00:00:00 2001 From: Akim Khalitov Date: Thu, 27 Aug 2026 22:24:13 +0400 Subject: [PATCH 3/3] docs(data-integration): one key name, and none where a row is a relationship MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sixteen bespoke key names — device_id, coverage_id, goal_id — were one idea wearing sixteen labels: the dataset is already known from the file, so the name carried nothing the column did not. They are record_id again. Only patients and encounters keep their own, because patient_identifier and encounter_id pair with a _system and become the resource's identifier. practitioners and care_team lose the key entirely. A row there is a relationship — a clinician at a location in a role, a member on a patient's team — and no roster has a primary key for one, so record_id could only be minted, and a minted key that is regenerated each export churns every resource it names. Both are keyed by the columns that define the relationship, which is how the Provider Directory feed already keys the same grain. --- ...allergies.4a0f3db1.csv => allergies.a73e091b.csv} | 2 +- ...re_plans.a7a2d06d.csv => care_plans.2fc221c8.csv} | 2 +- assets/data-integration/care_team.50c89a77.csv | 4 ---- assets/data-integration/care_team.b875e2b2.csv | 4 ++++ ...84386b.csv => clinical_observations.62d1ab2a.csv} | 2 +- ...nditions.eb153b88.csv => conditions.88f95a55.csv} | 2 +- .../{coverage.4d9e6894.csv => coverage.45cd4f72.csv} | 2 +- .../{devices.2ac2aa78.csv => devices.80ff669f.csv} | 2 +- ....f5a3daa0.csv => diagnostic_reports.0e3e56bc.csv} | 2 +- ...documents.4c460535.csv => documents.121ef115.csv} | 2 +- .../{goals.7ce937f2.csv => goals.f393bfdf.csv} | 2 +- ...tions.908bf32d.csv => immunizations.763fe971.csv} | 2 +- ...locations.8fd5cc92.csv => locations.4d522842.csv} | 2 +- assets/data-integration/practitioners.8d3ebf30.csv | 4 ++++ assets/data-integration/practitioners.961c4aea.csv | 4 ---- ...ocedures.ab0fa51c.csv => procedures.f61e2bc0.csv} | 2 +- ...ons.9ea0a20e.csv => related_persons.8c1bfb5d.csv} | 2 +- ...ts.134c537d.csv => service_requests.82e88e26.csv} | 2 +- ...tory.d2f5c741.csv => social_history.1d8b2b61.csv} | 2 +- ...l_signs.a2c1821b.csv => vital_signs.2a40ea2e.csv} | 2 +- docs/data-integration/README.md | 2 +- docs/data-integration/uscdi/allergies.md | 4 ++-- docs/data-integration/uscdi/care-plans.md | 4 ++-- docs/data-integration/uscdi/care-team.md | 12 +++++++----- docs/data-integration/uscdi/clinical-notes.md | 8 ++++---- docs/data-integration/uscdi/clinical-tests.md | 8 ++++---- docs/data-integration/uscdi/conditions.md | 4 ++-- docs/data-integration/uscdi/devices.md | 4 ++-- docs/data-integration/uscdi/encounters.md | 6 +++--- docs/data-integration/uscdi/goals.md | 4 ++-- docs/data-integration/uscdi/health-insurance.md | 4 ++-- docs/data-integration/uscdi/immunizations.md | 4 ++-- docs/data-integration/uscdi/patient-demographics.md | 8 ++++---- docs/data-integration/uscdi/procedures.md | 10 +++++----- docs/data-integration/uscdi/vital-signs.md | 4 ++-- 35 files changed, 68 insertions(+), 66 deletions(-) rename assets/data-integration/{allergies.4a0f3db1.csv => allergies.a73e091b.csv} (65%) rename assets/data-integration/{care_plans.a7a2d06d.csv => care_plans.2fc221c8.csv} (69%) delete mode 100644 assets/data-integration/care_team.50c89a77.csv create mode 100644 assets/data-integration/care_team.b875e2b2.csv rename assets/data-integration/{clinical_observations.9984386b.csv => clinical_observations.62d1ab2a.csv} (69%) rename assets/data-integration/{conditions.eb153b88.csv => conditions.88f95a55.csv} (75%) rename assets/data-integration/{coverage.4d9e6894.csv => coverage.45cd4f72.csv} (63%) rename assets/data-integration/{devices.2ac2aa78.csv => devices.80ff669f.csv} (84%) rename assets/data-integration/{diagnostic_reports.f5a3daa0.csv => diagnostic_reports.0e3e56bc.csv} (87%) rename assets/data-integration/{documents.4c460535.csv => documents.121ef115.csv} (72%) rename assets/data-integration/{goals.7ce937f2.csv => goals.f393bfdf.csv} (66%) rename assets/data-integration/{immunizations.908bf32d.csv => immunizations.763fe971.csv} (57%) rename assets/data-integration/{locations.8fd5cc92.csv => locations.4d522842.csv} (61%) create mode 100644 assets/data-integration/practitioners.8d3ebf30.csv delete mode 100644 assets/data-integration/practitioners.961c4aea.csv rename assets/data-integration/{procedures.ab0fa51c.csv => procedures.f61e2bc0.csv} (64%) rename assets/data-integration/{related_persons.9ea0a20e.csv => related_persons.8c1bfb5d.csv} (63%) rename assets/data-integration/{service_requests.134c537d.csv => service_requests.82e88e26.csv} (67%) rename assets/data-integration/{social_history.d2f5c741.csv => social_history.1d8b2b61.csv} (76%) rename assets/data-integration/{vital_signs.a2c1821b.csv => vital_signs.2a40ea2e.csv} (71%) diff --git a/assets/data-integration/allergies.4a0f3db1.csv b/assets/data-integration/allergies.a73e091b.csv similarity index 65% rename from assets/data-integration/allergies.4a0f3db1.csv rename to assets/data-integration/allergies.a73e091b.csv index 3589b7b..f197fa4 100644 --- a/assets/data-integration/allergies.4a0f3db1.csv +++ b/assets/data-integration/allergies.a73e091b.csv @@ -1,4 +1,4 @@ -allergy_id,patient_identifier,substance_code,substance_system,clinical_status,verification_status,category,criticality,reaction_manifestation_code,onset_date,is_deleted +record_id,patient_identifier,substance_code,substance_system,clinical_status,verification_status,category,criticality,reaction_manifestation_code,onset_date,is_deleted AL-0001,MRN-4471903,7980,,active,confirmed,medication,high,247472004,2019-05-02, AL-0002,MRN-5510042,7980,,active,,,,,, AL-0003,MRN-7782200,716186003,http://snomed.info/sct,active,confirmed,,,,, diff --git a/assets/data-integration/care_plans.a7a2d06d.csv b/assets/data-integration/care_plans.2fc221c8.csv similarity index 69% rename from assets/data-integration/care_plans.a7a2d06d.csv rename to assets/data-integration/care_plans.2fc221c8.csv index 1c3d475..bad9e7d 100644 --- a/assets/data-integration/care_plans.a7a2d06d.csv +++ b/assets/data-integration/care_plans.2fc221c8.csv @@ -1,4 +1,4 @@ -care_plan_id,patient_identifier,narrative_text,status,intent,period_start,period_end,is_deleted +record_id,patient_identifier,narrative_text,status,intent,period_start,period_end,is_deleted CP-0001,MRN-4471903,Assessment: … Plan: …,active,plan,2026-04-18,, CP-0002,MRN-7782200,Assessment: … Plan: …,completed,plan,2025-01-06,2025-12-31, CP-0003,MRN-5510042,Assessment: … Plan: …,draft,proposal,,, diff --git a/assets/data-integration/care_team.50c89a77.csv b/assets/data-integration/care_team.50c89a77.csv deleted file mode 100644 index f1289fc..0000000 --- a/assets/data-integration/care_team.50c89a77.csv +++ /dev/null @@ -1,4 +0,0 @@ -care_team_id,patient_identifier,member_npi,member_related_person_id,role_code,status,is_deleted -CT-0001,MRN-4471903,9999999991,,446050000,active, -CT-0002,MRN-4471903,,RP-3310,446050000,active, -CT-0003,MRN-7782200,9999999992,,446050000,inactive, diff --git a/assets/data-integration/care_team.b875e2b2.csv b/assets/data-integration/care_team.b875e2b2.csv new file mode 100644 index 0000000..a4fac82 --- /dev/null +++ b/assets/data-integration/care_team.b875e2b2.csv @@ -0,0 +1,4 @@ +patient_identifier,member_npi,member_related_person_id,role_code,status,is_deleted +MRN-4471903,9999999991,,446050000,active, +MRN-4471903,,RP-3310,446050000,active, +MRN-7782200,9999999992,,446050000,inactive, diff --git a/assets/data-integration/clinical_observations.9984386b.csv b/assets/data-integration/clinical_observations.62d1ab2a.csv similarity index 69% rename from assets/data-integration/clinical_observations.9984386b.csv rename to assets/data-integration/clinical_observations.62d1ab2a.csv index ff4a76f..76ea183 100644 --- a/assets/data-integration/clinical_observations.9984386b.csv +++ b/assets/data-integration/clinical_observations.62d1ab2a.csv @@ -1,4 +1,4 @@ -observation_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,is_deleted +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,is_deleted CO-1200,MRN-3391077,sdoh,final,76504-0,http://loinc.org,3,{score},,,,,2026-04-18,,,, CO-0002,MRN-3391077,sdoh,final,76504-0,http://loinc.org,,,,,,asked-declined,2026-04-18,,CO-1200,, CO-0003,MRN-4471903,exam,final,76504-0,http://loinc.org,,,No abnormality detected,,,,2026-04-18,,,, diff --git a/assets/data-integration/conditions.eb153b88.csv b/assets/data-integration/conditions.88f95a55.csv similarity index 75% rename from assets/data-integration/conditions.eb153b88.csv rename to assets/data-integration/conditions.88f95a55.csv index 3d3abf9..c54225a 100644 --- a/assets/data-integration/conditions.eb153b88.csv +++ b/assets/data-integration/conditions.88f95a55.csv @@ -1,4 +1,4 @@ -condition_id,patient_identifier,category,code,code_system,clinical_status,verification_status,onset_date,abatement_date,recorded_date,asserted_date,encounter_id,is_deleted +record_id,patient_identifier,category,code,code_system,clinical_status,verification_status,onset_date,abatement_date,recorded_date,asserted_date,encounter_id,is_deleted CND-0001,MRN-4471903,problem-list-item,44054006,http://snomed.info/sct,active,confirmed,2021-08-14,,2021-08-15,,, CND-0002,MRN-4471903,problem-list-item,44054006,http://snomed.info/sct,resolved,confirmed,2019-02-03,2023-11-30,2019-02-04,,, CND-4501,MRN-7782200,encounter-diagnosis,44054006,http://snomed.info/sct,active,confirmed,,,2026-04-18,,ENC-9913, diff --git a/assets/data-integration/coverage.4d9e6894.csv b/assets/data-integration/coverage.45cd4f72.csv similarity index 63% rename from assets/data-integration/coverage.4d9e6894.csv rename to assets/data-integration/coverage.45cd4f72.csv index 063915d..87845cf 100644 --- a/assets/data-integration/coverage.4d9e6894.csv +++ b/assets/data-integration/coverage.45cd4f72.csv @@ -1,4 +1,4 @@ -coverage_id,patient_identifier,status,member_id,subscriber_id,relationship_code,coverage_type_code,payer_org_npi,group_number,group_name,plan_number,plan_name,period_start,period_end,is_deleted +record_id,patient_identifier,status,member_id,subscriber_id,relationship_code,coverage_type_code,payer_org_npi,group_number,group_name,plan_number,plan_name,period_start,period_end,is_deleted COV-0001,MRN-4471903,active,HSX9930012,HSX9930012,self,1,9999999993,GRP-4410,Acme Manufacturing,H6776-001,Gold PPO,2026-01-01,2026-12-31, COV-0002,MRN-3391077,active,HSX9930013,HSX9930012,spouse,1,9999999993,,,,,2026-01-01,2026-12-31, COV-0003,MRN-4471903,cancelled,HSX8820001,HSX8820001,self,,9999999993,,,,,2025-01-01,2025-12-31, diff --git a/assets/data-integration/devices.2ac2aa78.csv b/assets/data-integration/devices.80ff669f.csv similarity index 84% rename from assets/data-integration/devices.2ac2aa78.csv rename to assets/data-integration/devices.80ff669f.csv index c6bc9e6..5b0e3e7 100644 --- a/assets/data-integration/devices.2ac2aa78.csv +++ b/assets/data-integration/devices.80ff669f.csv @@ -1,3 +1,3 @@ -device_id,patient_identifier,udi_device_identifier,udi_carrier_hrf,device_type_code,device_type_system,distinct_identifier,lot_number,serial_number,manufacture_date,expiration_date,is_deleted +record_id,patient_identifier,udi_device_identifier,udi_carrier_hrf,device_type_code,device_type_system,distinct_identifier,lot_number,serial_number,manufacture_date,expiration_date,is_deleted DV-0001,MRN-4471903,00643169007222,(01)00643169007222(17)…,468063009,http://snomed.info/sct,456,543211,842026,2019-03-01,2029-03-01, DV-0002,MRN-7782200,00643169007222,,468063009,http://snomed.info/sct,,,,,, diff --git a/assets/data-integration/diagnostic_reports.f5a3daa0.csv b/assets/data-integration/diagnostic_reports.0e3e56bc.csv similarity index 87% rename from assets/data-integration/diagnostic_reports.f5a3daa0.csv rename to assets/data-integration/diagnostic_reports.0e3e56bc.csv index 4e40238..57ce966 100644 --- a/assets/data-integration/diagnostic_reports.f5a3daa0.csv +++ b/assets/data-integration/diagnostic_reports.0e3e56bc.csv @@ -1,4 +1,4 @@ -report_id,patient_identifier,report_kind,status,code,code_system,category_code,effective_datetime,issued,performer_npi,attachment_file,encounter_id,is_deleted +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/documents.4c460535.csv b/assets/data-integration/documents.121ef115.csv similarity index 72% rename from assets/data-integration/documents.4c460535.csv rename to assets/data-integration/documents.121ef115.csv index 3a18bb3..cfc4fa4 100644 --- a/assets/data-integration/documents.4c460535.csv +++ b/assets/data-integration/documents.121ef115.csv @@ -1,4 +1,4 @@ -document_id,patient_identifier,type_code,attachment_file,document_date,author_npi,encounter_id,is_deleted +record_id,patient_identifier,type_code,attachment_file,document_date,author_npi,encounter_id,is_deleted DOC-0001,MRN-4471903,11488-4,attachments/DOC-0001.pdf,2026-04-18T10:00:00-04:00,9999999991,ENC-9912, DOC-0002,MRN-7782200,18842-5,attachments/DOC-0002.pdf,2026-02-06T11:30:00-05:00,9999999991,ENC-9913, DOC-0003,MRN-5510042,11506-3,attachments/DOC-0003.pdf,2026-01-09T15:05:00-05:00,,, diff --git a/assets/data-integration/goals.7ce937f2.csv b/assets/data-integration/goals.f393bfdf.csv similarity index 66% rename from assets/data-integration/goals.7ce937f2.csv rename to assets/data-integration/goals.f393bfdf.csv index b70d4ca..60996be 100644 --- a/assets/data-integration/goals.7ce937f2.csv +++ b/assets/data-integration/goals.f393bfdf.csv @@ -1,4 +1,4 @@ -goal_id,patient_identifier,lifecycle_status,description_code,description_system,start_date,target_date,is_deleted +record_id,patient_identifier,lifecycle_status,description_code,description_system,start_date,target_date,is_deleted GL-0001,MRN-4471903,active,289169006,http://snomed.info/sct,2026-04-18,2026-10-18, GL-0002,MRN-7782200,completed,289169006,http://snomed.info/sct,2025-03-01,2025-09-01, GL-0003,MRN-5510042,proposed,289169006,http://snomed.info/sct,,, diff --git a/assets/data-integration/immunizations.908bf32d.csv b/assets/data-integration/immunizations.763fe971.csv similarity index 57% rename from assets/data-integration/immunizations.908bf32d.csv rename to assets/data-integration/immunizations.763fe971.csv index 6ae4b29..e7641e1 100644 --- a/assets/data-integration/immunizations.908bf32d.csv +++ b/assets/data-integration/immunizations.763fe971.csv @@ -1,4 +1,4 @@ -immunization_id,patient_identifier,status,status_reason_code,status_reason_system,vaccine_code,vaccine_system,occurrence_date,performer_npi,primary_source,is_deleted +record_id,patient_identifier,status,status_reason_code,status_reason_system,vaccine_code,vaccine_system,occurrence_date,performer_npi,primary_source,is_deleted IM-0001,MRN-4471903,completed,,,140,,2025-10-02,9999999991,true, IM-0002,MRN-7782200,not-done,PATOBJ,http://terminology.hl7.org/CodeSystem/v3-ActReason,140,,2025-11-14,,, IM-0003,MRN-5510042,completed,,,140,,2019-09-30,,false, diff --git a/assets/data-integration/locations.8fd5cc92.csv b/assets/data-integration/locations.4d522842.csv similarity index 61% rename from assets/data-integration/locations.8fd5cc92.csv rename to assets/data-integration/locations.4d522842.csv index 124dd00..ec3832f 100644 --- a/assets/data-integration/locations.8fd5cc92.csv +++ b/assets/data-integration/locations.4d522842.csv @@ -1,3 +1,3 @@ -location_id,location_name,managing_org_npi,address_line1,city,state,zip,is_deleted +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/assets/data-integration/practitioners.8d3ebf30.csv b/assets/data-integration/practitioners.8d3ebf30.csv new file mode 100644 index 0000000..00e3935 --- /dev/null +++ b/assets/data-integration/practitioners.8d3ebf30.csv @@ -0,0 +1,4 @@ +npi,last_name,first_name,specialty_nucc,primary_org_npi,practitioner_role_code,location_id,phone,email,role_period_start,role_period_end,is_deleted +9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-221,5551234567,,2021-04-01,, +9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-884,5554445555,,,, +9999999992,Fox,Dana,,,,,,,,, diff --git a/assets/data-integration/practitioners.961c4aea.csv b/assets/data-integration/practitioners.961c4aea.csv deleted file mode 100644 index 5e2c837..0000000 --- a/assets/data-integration/practitioners.961c4aea.csv +++ /dev/null @@ -1,4 +0,0 @@ -practitioner_role_id,npi,last_name,first_name,specialty_nucc,primary_org_npi,practitioner_role_code,location_id,phone,email,role_period_start,role_period_end,is_deleted -PRC-0001,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-221,5551234567,,2021-04-01,, -PRC-0002,9999999991,Roe,Richard,207R00000X,9999999993,PCP,LOC-884,5554445555,,,, -PRC-0003,9999999992,Fox,Dana,,,,,,,,, diff --git a/assets/data-integration/procedures.ab0fa51c.csv b/assets/data-integration/procedures.f61e2bc0.csv similarity index 64% rename from assets/data-integration/procedures.ab0fa51c.csv rename to assets/data-integration/procedures.f61e2bc0.csv index c4b41e5..7b07f7a 100644 --- a/assets/data-integration/procedures.ab0fa51c.csv +++ b/assets/data-integration/procedures.f61e2bc0.csv @@ -1,4 +1,4 @@ -procedure_id,patient_identifier,status,code,code_system,performed_start,performed_end,performer_npi,encounter_id,service_request_id,reason_code,reason_system,is_deleted +record_id,patient_identifier,status,code,code_system,performed_start,performed_end,performer_npi,encounter_id,service_request_id,reason_code,reason_system,is_deleted PRO-0001,MRN-4471903,completed,80146002,http://snomed.info/sct,2026-04-18,,9999999991,ENC-9912,,,, PRO-0002,MRN-7782200,completed,80146002,http://snomed.info/sct,2026-02-02,2026-02-02,9999999991,ENC-9913,,,, PRO-0003,MRN-3391077,completed,80146002,http://snomed.info/sct,2026-05-24,,,,SR-2201,733423003,, diff --git a/assets/data-integration/related_persons.9ea0a20e.csv b/assets/data-integration/related_persons.8c1bfb5d.csv similarity index 63% rename from assets/data-integration/related_persons.9ea0a20e.csv rename to assets/data-integration/related_persons.8c1bfb5d.csv index 52620a1..0f946da 100644 --- a/assets/data-integration/related_persons.9ea0a20e.csv +++ b/assets/data-integration/related_persons.8c1bfb5d.csv @@ -1,4 +1,4 @@ -related_person_id,patient_identifier,relationship_code,last_name,first_name,phone,address_line1,city,state,zip,active,is_deleted +record_id,patient_identifier,relationship_code,last_name,first_name,phone,address_line1,city,state,zip,active,is_deleted RP-3310,MRN-4471903,DAU,Doe,Mary,5559876543,45 Oak St,Anytown,NY,12345,true, RP-0002,MRN-4471903,SPS,Doe,Robert,,,,,,true, RP-0003,MRN-7782200,GUARD,Poe,Alan,5552223333,,,,,false, diff --git a/assets/data-integration/service_requests.134c537d.csv b/assets/data-integration/service_requests.82e88e26.csv similarity index 67% rename from assets/data-integration/service_requests.134c537d.csv rename to assets/data-integration/service_requests.82e88e26.csv index 89e9f2f..7d45ebc 100644 --- a/assets/data-integration/service_requests.134c537d.csv +++ b/assets/data-integration/service_requests.82e88e26.csv @@ -1,4 +1,4 @@ -service_request_id,patient_identifier,status,intent,code,code_system,category,category_system,reason_code,reason_system,authored_on,occurrence_date,requester_npi,is_deleted +record_id,patient_identifier,status,intent,code,code_system,category,category_system,reason_code,reason_system,authored_on,occurrence_date,requester_npi,is_deleted SR-2201,MRN-3391077,active,order,103696004,http://snomed.info/sct,sdoh,http://hl7.org/fhir/us/core/CodeSystem/us-core-category,733423003,,2026-05-10,2026-05-24,9999999991, SR-0002,MRN-4471903,active,order,103696004,http://snomed.info/sct,,,,,2026-04-18,,9999999991, SR-0003,MRN-7782200,completed,plan,103696004,http://snomed.info/sct,,,,,2025-12-01,,, diff --git a/assets/data-integration/social_history.d2f5c741.csv b/assets/data-integration/social_history.1d8b2b61.csv similarity index 76% rename from assets/data-integration/social_history.d2f5c741.csv rename to assets/data-integration/social_history.1d8b2b61.csv index 17020b5..08f6a04 100644 --- a/assets/data-integration/social_history.d2f5c741.csv +++ b/assets/data-integration/social_history.1d8b2b61.csv @@ -1,4 +1,4 @@ -social_history_id,patient_identifier,observation_type,status,value_code,value_system,industry_code,effective_datetime,is_deleted +record_id,patient_identifier,observation_type,status,value_code,value_system,industry_code,effective_datetime,is_deleted SH-0001,MRN-4471903,occupation,final,29-1141.00,,622110,2026-04-18, SH-0002,MRN-4471903,smoking-status,final,266919005,http://snomed.info/sct,,2026-04-18, SH-0003,MRN-7782200,smoking-status,final,8517006,http://snomed.info/sct,,2026-02-11, diff --git a/assets/data-integration/vital_signs.a2c1821b.csv b/assets/data-integration/vital_signs.2a40ea2e.csv similarity index 71% rename from assets/data-integration/vital_signs.a2c1821b.csv rename to assets/data-integration/vital_signs.2a40ea2e.csv index b898467..0acefd7 100644 --- a/assets/data-integration/vital_signs.a2c1821b.csv +++ b/assets/data-integration/vital_signs.2a40ea2e.csv @@ -1,4 +1,4 @@ -vital_sign_id,patient_identifier,status,loinc_code,effective_datetime,value,unit,component_systolic,component_diastolic,encounter_id,performer_npi,is_deleted +record_id,patient_identifier,status,loinc_code,effective_datetime,value,unit,component_systolic,component_diastolic,encounter_id,performer_npi,is_deleted VS-0001,MRN-4471903,final,85354-9,2026-04-18T09:05:00-04:00,,,128,82,ENC-9912,9999999991, VS-0002,MRN-4471903,final,8867-4,2026-04-18T09:05:00-04:00,72,/min,,,ENC-9912,, VS-0003,MRN-4471903,final,8302-2,2026-04-18T09:05:00-04:00,163,cm,,,,, diff --git a/docs/data-integration/README.md b/docs/data-integration/README.md index 8d6146c..f7ad465 100644 --- a/docs/data-integration/README.md +++ b/docs/data-integration/README.md @@ -23,7 +23,7 @@ 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. | -| Keys (USCDI feed) | Each dataset names its own key column, listed first in its table. Payerbox derives the resource id from it, so keep it stable across deliveries: the same value updates the row in place, a new one creates a second resource. `is_deleted` set to `true` retracts the row it names. | +| Keys (USCDI feed) | Each dataset's table says what keys its rows: a key column listed first, or — where a row is a relationship rather than a record, as in `practitioners` and `care_team` — the columns that together identify it. Payerbox derives the resource id from that key, so keep it stable across deliveries: the same value updates the row in place, a new one creates a second resource. `is_deleted` set to `true` retracts the row it names. | | 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/allergies.md b/docs/data-integration/uscdi/allergies.md index 64647bd..adf454b 100644 --- a/docs/data-integration/uscdi/allergies.md +++ b/docs/data-integration/uscdi/allergies.md @@ -18,13 +18,13 @@ description: >- One row per substance per patient. A substance with several reaction manifestations stays one row: list the manifestation codes `;`-separated. -{% file src="../../assets/data-integration/allergies.4a0f3db1.csv" %} +{% file src="../../assets/data-integration/allergies.a73e091b.csv" %} allergies.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `allergy_id` | Yes | your key for this allergy | `AL-0001` | +| `record_id` | Yes | your key for this allergy | `AL-0001` | | `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 | | `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%7C4.0.1) | `active` | diff --git a/docs/data-integration/uscdi/care-plans.md b/docs/data-integration/uscdi/care-plans.md index 77ba5ea..02c12bc 100644 --- a/docs/data-integration/uscdi/care-plans.md +++ b/docs/data-integration/uscdi/care-plans.md @@ -18,13 +18,13 @@ description: >- One row per care plan. This dataset carries the **Assessment and Plan of Treatment** narrative; the SDOH Assessment element of the same class comes from `clinical_observations`. -{% file src="../../assets/data-integration/care_plans.a7a2d06d.csv" %} +{% file src="../../assets/data-integration/care_plans.2fc221c8.csv" %} care_plans.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `care_plan_id` | Yes | your key for this care plan | `CP-0001` | +| `record_id` | Yes | your key for this care plan | `CP-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `narrative_text` | Yes | text or HTML; the assessment and plan itself | `Assessment: … Plan: …` | | `status` | Yes | `draft`, `active`, `on-hold`, `revoked`, `completed`, `entered-in-error`, `unknown` [request-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/request-status%7C4.0.1) | `active` | diff --git a/docs/data-integration/uscdi/care-team.md b/docs/data-integration/uscdi/care-team.md index 78f10af..9d95f5f 100644 --- a/docs/data-integration/uscdi/care-team.md +++ b/docs/data-integration/uscdi/care-team.md @@ -21,13 +21,12 @@ One row per practitioner, organization, and location: each row becomes one Pract If you already send the [Provider Directory](../provider-directory/README.md) feed, list here only the clinicians missing from it, such as an external ordering physician. -{% file src="../../assets/data-integration/practitioners.961c4aea.csv" %} +{% file src="../../assets/data-integration/practitioners.8d3ebf30.csv" %} practitioners.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `practitioner_role_id` | Yes | your key for this practitioner-at-location row; `care_team` and `encounters` reference the `npi` | `PRC-0001` | | `npi` | Yes | 10 digits | `9999999991` | | `last_name` | Yes | text | `Roe` | | `first_name` | Recommended | text | `Richard` | @@ -40,21 +39,24 @@ practitioners.csv Data template with example rows | `role_period_start` | If available | date | `2021-04-01` | | `role_period_end` | If available | date | | +- A row is keyed by `npi`, `location_id` and `practitioner_role_code` together — the roster has no key of its own, so do not mint one. Keep those three stable and the role updates in place. + ## care_team One row per patient and team member. -{% file src="../../assets/data-integration/care_team.50c89a77.csv" %} +{% file src="../../assets/data-integration/care_team.b875e2b2.csv" %} care_team.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `care_team_id` | Yes | your key for this care team row | `CT-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `member_npi` | Yes, unless `member_related_person_id` is sent | 10 digits | `9999999991` | -| `member_related_person_id` | Yes, unless `member_npi` is sent | `related_person_id` of the `related_persons` row, for non-clinicians | `RP-3310` | +| `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` | +- A row is keyed by `patient_identifier`, the member (`member_npi` or `member_related_person_id`) and `role_code` together — a roster has no key of its own for a membership, so do not mint one. + 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 index af333ca..a202920 100644 --- a/docs/data-integration/uscdi/clinical-notes.md +++ b/docs/data-integration/uscdi/clinical-notes.md @@ -33,13 +33,13 @@ delivery-2026-08-19/ One row per note. The note itself is the file; this row is its index card. -{% file src="../../assets/data-integration/documents.4c460535.csv" %} +{% file src="../../assets/data-integration/documents.121ef115.csv" %} documents.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `document_id` | Yes | your key for this note | `DOC-0001` | +| `record_id` | Yes | your key for this note | `DOC-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `type_code` | Yes | LOINC note type, e.g. `11488-4` consult, `18842-5` discharge summary, `34117-2` history and physical, `11506-3` progress note [US Core DocumentReference Type](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-documentreference-type) | `11488-4` | | `attachment_file` | Yes | path relative to the delivery root | `attachments/DOC-0001.pdf` | @@ -54,13 +54,13 @@ documents.csv Data template with example rows One row per report. The individual results live in `labs` and `clinical_observations` and point back with `diagnostic_report_id`. -{% file src="../../assets/data-integration/diagnostic_reports.f5a3daa0.csv" %} +{% file src="../../assets/data-integration/diagnostic_reports.0e3e56bc.csv" %} diagnostic_reports.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `report_id` | Yes | your key for this report; result rows reference it | `DR-771` | +| `record_id` | Yes | your key for this report; result rows reference it | `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 a8d0ea9..bd58eb8 100644 --- a/docs/data-integration/uscdi/clinical-tests.md +++ b/docs/data-integration/uscdi/clinical-tests.md @@ -18,13 +18,13 @@ description: >- One row per observation. This dataset carries every USCDI observation that is not a lab result, a vital sign or a social history row: non-lab test results, imaging findings, functional, disability and cognitive status, and SDOH screening answers. -{% file src="../../assets/data-integration/clinical_observations.9984386b.csv" %} +{% file src="../../assets/data-integration/clinical_observations.62d1ab2a.csv" %} clinical_observations.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `observation_id` | Yes | your key for this observation; panel members reference it | `CO-1200` | +| `record_id` | Yes | your key for this observation; panel members reference it | `CO-1200` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `category` | Yes | one of the [categories](#categories) below | `sdoh` | | `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%7C4.0.1) | `final` | @@ -36,8 +36,8 @@ clinical_observations.csv Data template with example rows | `data_absent_reason` | If there is no result | `unknown`, `asked-declined`, `not-performed` [data-absent-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/data-absent-reason%7C4.0.1) | | | `effective_datetime` | Recommended | datetime | `2026-04-18` | | `performer_npi` | If available | 10 digits | `9999999991` | -| `panel_id` | If available | `observation_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` | +| `panel_id` | If available | `record_id` of the parent `clinical_observations` row | `CO-1200` | +| `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/conditions.md b/docs/data-integration/uscdi/conditions.md index 88ead72..5affb1b 100644 --- a/docs/data-integration/uscdi/conditions.md +++ b/docs/data-integration/uscdi/conditions.md @@ -18,13 +18,13 @@ description: >- One file covers all four USCDI condition flavours — problems, health concerns, encounter diagnoses, and SDOH — one row per condition per patient; the `category` column tells them apart. -{% file src="../../assets/data-integration/conditions.eb153b88.csv" %} +{% file src="../../assets/data-integration/conditions.88f95a55.csv" %} conditions.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `condition_id` | Yes | your key for this condition; `encounters` reference it | `CND-0001` | +| `record_id` | Yes | your key for this condition; `encounters` reference it | `CND-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `category` | Yes | one of seven values — see [Categories](#categories) | `problem-list-item` | | `code` | Yes | SNOMED CT or ICD-10-CM code, with `code_system` [us-core-condition-code](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-condition-code) | `44054006` Type 2 diabetes mellitus | diff --git a/docs/data-integration/uscdi/devices.md b/docs/data-integration/uscdi/devices.md index 23c98c3..52f7e0b 100644 --- a/docs/data-integration/uscdi/devices.md +++ b/docs/data-integration/uscdi/devices.md @@ -18,13 +18,13 @@ description: >- One row per implanted device per patient. The USCDI data class covers implantable devices only — other equipment does not belong in this file. -{% file src="../../assets/data-integration/devices.2ac2aa78.csv" %} +{% file src="../../assets/data-integration/devices.80ff669f.csv" %} devices.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `device_id` | Yes | your key for this device row | `DV-0001` | +| `record_id` | Yes | your key for this device row | `DV-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `udi_device_identifier` | Yes | DI portion of the UDI | `00643169007222` | | `udi_carrier_hrf` | Recommended | full UDI barcode string, human-readable form | `(01)00643169007222(17)…` | diff --git a/docs/data-integration/uscdi/encounters.md b/docs/data-integration/uscdi/encounters.md index 62440f3..89b9105 100644 --- a/docs/data-integration/uscdi/encounters.md +++ b/docs/data-integration/uscdi/encounters.md @@ -35,7 +35,7 @@ encounters.csv Data template with example rows | `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` | -| `diagnosis_condition_id` | If available | `condition_id` of the `conditions` row(s), `;`-separated | `CND-4501` | +| `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` | | `discharge_disposition_code` | If applicable | NUBC patient discharge status code, as carried in UB-04 field 17, with `discharge_disposition_system` [AHA NUBC Patient Discharge Status](https://terminology.hl7.org/5.5.0/CodeSystem-AHANUBCPatientDischargeStatus.html) | `01` discharged to home or self-care | @@ -51,13 +51,13 @@ One row per physical location: a clinic, a hospital ward, a lab draw station. If you already send the [Provider Directory](../provider-directory/README.md) feed, list here only the locations missing from it, such as a facility outside your network where a member was treated. -{% file src="../../assets/data-integration/locations.8fd5cc92.csv" %} +{% file src="../../assets/data-integration/locations.4d522842.csv" %} locations.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `location_id` | Yes | your key for this location; `encounters` and `practitioners` reference it | `LOC-221` | +| `record_id` | Yes | your key for this location; `encounters` and `practitioners` reference it | `LOC-221` | | `location_name` | Yes | text | `Anytown Family Practice` | | `managing_org_npi` | Recommended | 10 digits | `9999999993` | | `address_line1` | Recommended | text | `123 Main St` | diff --git a/docs/data-integration/uscdi/goals.md b/docs/data-integration/uscdi/goals.md index a61920e..ab11a78 100644 --- a/docs/data-integration/uscdi/goals.md +++ b/docs/data-integration/uscdi/goals.md @@ -18,13 +18,13 @@ description: >- One row per goal per patient. -{% file src="../../assets/data-integration/goals.7ce937f2.csv" %} +{% file src="../../assets/data-integration/goals.f393bfdf.csv" %} goals.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `goal_id` | Yes | your key for this goal | `GL-0001` | +| `record_id` | Yes | your key for this goal | `GL-0001` | | `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) | `289169006` exercising to lose weight | diff --git a/docs/data-integration/uscdi/health-insurance.md b/docs/data-integration/uscdi/health-insurance.md index 776eb31..dcea90c 100644 --- a/docs/data-integration/uscdi/health-insurance.md +++ b/docs/data-integration/uscdi/health-insurance.md @@ -18,13 +18,13 @@ description: >- One row per coverage. A member with more than one plan, or a plan year that changed mid-year, produces more than one row. -{% file src="../../assets/data-integration/coverage.4d9e6894.csv" %} +{% file src="../../assets/data-integration/coverage.45cd4f72.csv" %} coverage.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `coverage_id` | Yes | your key for this coverage | `COV-0001` | +| `record_id` | Yes | your key for this coverage | `COV-0001` | | `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` | Yes, unless `subscriber_id` is sent | plan member id | `HSX9930012` | diff --git a/docs/data-integration/uscdi/immunizations.md b/docs/data-integration/uscdi/immunizations.md index 620341c..f684237 100644 --- a/docs/data-integration/uscdi/immunizations.md +++ b/docs/data-integration/uscdi/immunizations.md @@ -20,13 +20,13 @@ description: >- One row per administered (or refused) dose per patient. A member with three seasonal flu shots is three rows. -{% file src="../../assets/data-integration/immunizations.908bf32d.csv" %} +{% file src="../../assets/data-integration/immunizations.763fe971.csv" %} immunizations.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `immunization_id` | Yes | your key for this dose | `IM-0001` | +| `record_id` | Yes | your key for this dose | `IM-0001` | | `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%7C4.0.1) | `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%7C4.0.1) | `PATOBJ` patient objection | diff --git a/docs/data-integration/uscdi/patient-demographics.md b/docs/data-integration/uscdi/patient-demographics.md index e57dfee..bcedb53 100644 --- a/docs/data-integration/uscdi/patient-demographics.md +++ b/docs/data-integration/uscdi/patient-demographics.md @@ -93,13 +93,13 @@ patients.csv Data template with example rows Contacts and non-clinician care-team members, such as a daughter, spouse, or guardian. One row per person per patient. -{% file src="../../assets/data-integration/related_persons.9ea0a20e.csv" %} +{% file src="../../assets/data-integration/related_persons.8c1bfb5d.csv" %} related_persons.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `related_person_id` | Yes | your key for this person; `care_team` references it | `RP-3310` | +| `record_id` | Yes | your key for this person; `care_team` references it | `RP-3310` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `relationship_code` | Recommended | `DAU` daughter, `SPS` spouse, `CHILD` child [v3-RoleCode](https://terminology.hl7.org/CodeSystem-v3-RoleCode.html), [v2-0131](https://terminology.hl7.org/CodeSystem-v2-0131.html) | `DAU` | | `last_name` | Recommended | text | `Doe` | @@ -113,13 +113,13 @@ related_persons.csv Data template with example rows ## social_history -{% file src="../../assets/data-integration/social_history.d2f5c741.csv" %} +{% file src="../../assets/data-integration/social_history.1d8b2b61.csv" %} social_history.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `social_history_id` | Yes | your key for this row | `SH-0001` | +| `record_id` | Yes | your key for this row | `SH-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `observation_type` | Yes | `occupation` for the demographics rows; `smoking-status`, `pregnancy-status`, `pregnancy-intent` are Health Status/Assessments | `occupation` | | `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%7C4.0.1) | `final` | diff --git a/docs/data-integration/uscdi/procedures.md b/docs/data-integration/uscdi/procedures.md index 9e73f77..42079a7 100644 --- a/docs/data-integration/uscdi/procedures.md +++ b/docs/data-integration/uscdi/procedures.md @@ -19,13 +19,13 @@ description: >- One row per procedure performed. This dataset carries the **Procedures** element of the class. -{% file src="../../assets/data-integration/procedures.ab0fa51c.csv" %} +{% file src="../../assets/data-integration/procedures.f61e2bc0.csv" %} procedures.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `procedure_id` | Yes | your key for this procedure | `PRO-0001` | +| `record_id` | Yes | your key for this procedure | `PRO-0001` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `status` | Yes | `preparation`, `in-progress`, `on-hold`, `stopped`, `completed`, `not-done`, `entered-in-error`, `unknown` [event-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/event-status%7C4.0.1) | `completed` | | `code` | Yes | CPT, HCPCS, ICD-10-PCS, or SNOMED CT code, with `code_system`; CPT if omitted [US Core Procedure Codes](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-procedure-code) | `80146002` appendectomy | @@ -33,7 +33,7 @@ procedures.csv Data template with example rows | `performed_end` | If a period | date or datetime | | | `performer_npi` | If available | 10 digits | `9999999991` | | `encounter_id` | If applicable | `encounters` key | `ENC-9912` | -| `service_request_id` | If available | `service_request_id` of the `service_requests` row, when the procedure fulfils a request | `SR-2201` | +| `service_request_id` | If available | `record_id` of the `service_requests` row, when the procedure fulfils a request | `SR-2201` | | `reason_code` | If available | SNOMED CT or ICD-10-CM code(s), `;`-separated, with `reason_system`; SNOMED CT if omitted [procedure-reason](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/procedure-reason%7C4.0.1) | `733423003` food insecurity | - `performed_end` marks a procedure that spans time. Send it only then; a single `performed_start` is a point in time. @@ -43,13 +43,13 @@ procedures.csv Data template with example rows One row per requested service: a referral, an order, or an SDOH intervention. This dataset carries the **Reason for Referral** and **SDOH Interventions** elements of the class; the services actually performed go in `procedures`. -{% file src="../../assets/data-integration/service_requests.134c537d.csv" %} +{% file src="../../assets/data-integration/service_requests.82e88e26.csv" %} service_requests.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `service_request_id` | Yes | your key for this request; `procedures` reference it | `SR-2201` | +| `record_id` | Yes | your key for this request; `procedures` reference it | `SR-2201` | | `patient_identifier` | Yes | patient key | `MRN-4471903` | | `status` | Yes | `draft`, `active`, `on-hold`, `completed`, `revoked`, `entered-in-error`, `unknown` [request-status](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/request-status%7C4.0.1) | `active` | | `intent` | Yes | `proposal`, `plan`, `directive`, `order`, `original-order`, `reflex-order`, `filler-order`, `instance-order`, `option` [request-intent](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/ValueSet/request-intent%7C4.0.1) | `order` | diff --git a/docs/data-integration/uscdi/vital-signs.md b/docs/data-integration/uscdi/vital-signs.md index d5e645b..f383659 100644 --- a/docs/data-integration/uscdi/vital-signs.md +++ b/docs/data-integration/uscdi/vital-signs.md @@ -18,13 +18,13 @@ description: >- One row per measurement, except blood pressure: systolic and diastolic are two components of a single reading, so they share a row. -{% file src="../../assets/data-integration/vital_signs.a2c1821b.csv" %} +{% file src="../../assets/data-integration/vital_signs.2a40ea2e.csv" %} vital_signs.csv Data template with example rows {% endfile %} | Column | Required | Format / values | Example | |---|---|---|---| -| `vital_sign_id` | Yes | your key for this reading | `VS-0001` | +| `record_id` | Yes | your key for this reading | `VS-0001` | | `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%7C4.0.1) | `final` | | `loinc_code` | Yes | one of the [vital sign codes](#vital-sign-codes) below [US Core Vital Signs](https://healthsamurai.github.io/fhir-valueset-viewer/#url=http://hl7.org/fhir/us/core/ValueSet/us-core-vital-signs) | `8867-4` |