HL7 Vietnam VN Core FHIR Implementation Guide

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.6.0 - Draft for Community Review Viet Nam cờ

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.6.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Lịch sử thay đổi

Lịch sử thay đổi — Changelog

Lịch sử thay đổi theo từng phiên bản.

Cách dùng changelog

  • Nếu bạn đang nâng phiên bản, hãy đọc từ phiên bản mới nhất trở xuống và tập trung vào các thay đổi có khả năng ảnh hưởng đến ánh xạ dữ liệu, validation, package dependency và hành vi tìm kiếm.
  • Nếu bạn là reviewer hoặc thành viên cộng đồng, hãy dùng changelog để theo dõi hướng trưởng thành của IG, không dùng nó thay cho tài liệu hướng dẫn triển khai.
  • Nếu bạn cần quyết định có nên nâng phiên bản ngay hay chưa, hãy đọc thêm Ổn định và tuân thủ và Phát hành và quản trị.

Phiên bản 0.6.0 — Draft for Community Review (2026-06-04)

Trạng thái: Bản công bố hiện hành — minor release trên nền 0.5.3. Profiles 52 → 71. Chưa đổi canonical URL/package id.

Thêm mới — Quản lý chăm sóc (care management)

  • VNCoreCarePlan, VNCoreCareTeam, VNCoreGoal, VNCoreEpisodeOfCare, VNCoreClinicalImpression — bộ profile quản lý chăm sóc/điều trị (TT 13/2025), khép bộ ba CarePlan → Goal → CareTeam.
  • VNCoreMedicationStatement, VNCoreMedicationAdministration — tiền sử dùng thuốc + cho dùng thuốc nội trú, khép chuỗi kê đơn → cấp phát → sử dụng.
  • VNCoreObservationTriageAcuity + VNTriageAcuityCS/VNTriageAcuityVS — thang phân loại ưu tiên cấp cứu 5 mức (thang đề xuất nội bộ tham chiếu ATS; QĐ 01/2008 làm căn cứ nguyên tắc ưu tiên — xem ADR-0014). Thêm VNValidationRuleCS, VNPrescriptionCodeNS.

Thêm mới — KSK liên thông (Structured Data Capture)

  • VNCoreQuestionnaire + VNCoreQuestionnaireResponse (HL7 SDC) + 17 mẫu phiếu VNKSKQuestionnaire01–17 theo QĐ 1551/QĐ-BYT Phụ lục 01 (linkId = mã trường). Xem ADR-0015.
  • VNCoreFamilyMemberHistory — tiền sử gia đình (mục III.A phiếu KSK).

Thêm mới — Tương tác quốc tế (IPS dual-profile)

  • VNCoreCompositionIPS (kế thừa Composition-uv-ips) + operation $summary (vn-generate-ips-summary, projection Sổ SKĐT nội địa → IPS Bundle). Dependency hl7.fhir.uv.ips#2.0.0; cầu thuật ngữ SNOMED CT qua VNSNOMEDSubsetCS. Xem ADR-0016.

Thay đổi — Conformance & corpus

  • VNCoreServer khai báo thêm 8 resource (EpisodeOfCare, CarePlan, CareTeam, Goal, ClinicalImpression, MedicationStatement, MedicationDispense, MedicationAdministration) + $summary.
  • VNLegalDocumentRefCS: + QĐ 2919 (chuẩn dữ liệu Giấy chứng sinh, tách Bảng 9 khỏi chuỗi QĐ 130 → 4750 → 3176) → 132 concepts; public legal registry mirror đủ 132 mục có nguồn đối chiếu; actionable legal citation coverage 83/83 (100%).
  • Số liệu (sau hardening): profiles 52→71, CodeSystems 75→139, ValueSets 81→144, extensions 48 (45 cục bộ + 3 HL7), NamingSystems 25→32, ConceptMaps 5→6.

Hardened — độ chín SDC/IPS/SNOMED (review độc lập)

  • KSK = HL7 SDC thật: dependency hl7.fhir.uv.sdc#4.0.0; profile dẫn xuất sdc-questionnaire/sdc-questionnaireresponse; formal-hoá toàn bộ 5.523 answer code (285 hệ ad-hoc → 56 CodeSystem chính thức theo QĐ 1551), 707 field → answerValueSet, thêm required, 17 Questionnaire khai báo artifact-versionAlgorithm=semver. Xem ADR-0015.
  • IPS end-to-end: VNCoreBundleIPS (type=document) + ví dụ document Bundle hợp lệ + $summary contract. Xem ADR-0016.
  • Cầu SNOMED: ConceptMap ICD-10 VN → SNOMED CT.
  • Số liệu sau hardening: profiles 71, CodeSystems 141, ValueSets 146, ConceptMaps 6.

Phiên bản 0.5.3 — Draft for Community Review Patch (2026-05-30)

Trạng thái: Bản patch trước đó — additive core-bound patch trên nền 0.5.2

Ảnh chụp phát hành

  • 52 hồ sơ, 45 phần mở rộng cục bộ + 3 chuẩn HL7, 75 CodeSystems, 81 ValueSets, 5 ConceptMaps
  • 19 SearchParameters, 25 NamingSystems, 13 logical models, 3 OperationDefinitions, 5 CapabilityStatements
  • 157 tệp ví dụ / 159 thực thể ví dụ, 302 total instances, 496 exported JSON artifacts
  • VNLegalDocumentRefCS mở rộng lên 117 concepts (registry máy đọc); registry public giai đoạn v0.5 có 101 mục nguồn TVPL exact; trạng thái public hiện hành của v0.6.0 là 132 nguồn; actionable legal citation coverage đạt 74/74 direct-technical documents (100%)

Nội dung patch

  • Thêm TT-30-2024 (TT 30/2024/TT-BYT — danh mục kỹ thuật, dịch vụ y tế cơ bản tại Trạm Y tế xã/phường) vào VNLegalDocumentRefCS, đưa registry máy đọc từ 116 → 117 concepts và actionable coverage 73/73 → 74/74.
  • Bổ sung VNBasicHealthServiceCS (74 concept lồng nhau) và VNBasicHealthServiceVS — danh mục dịch vụ y tế cơ bản tuyến xã theo TT 30/2024/TT-BYT, phục vụ IG phái sinh chăm sóc sức khỏe ban đầu (CHC).
  • Bổ sung VNServiceDeliverySettingCS (6 mã) và VNServiceDeliverySettingVS — phân loại bối cảnh cung cấp dịch vụ (tại trạm, tại nhà, lưu động, trường học…).
  • Bổ sung vòng đời mã cơ sở trên VNCoreOrganization: extension VNCoreExtOrgLifecycleRelation cùng VNOrgLifecycleRelationCS (4 mã) và VNOrgCarryOverItemCS (5 mã), thêm identifier.period và ví dụ ExampleOrganizationMergedStation — mô hình hóa sáp nhập/chia tách/đổi mã cơ sở KCB theo NQ 202/2025 và NĐ 102/2025.
  • Đồng bộ governance surface (release-manifest, roadmap, release-metrics 0.5.3, content-facts, wiki inventory, legal-corpus, package-architecture) theo 0.5.3.

Tác động nâng cấp

  • Không đổi canonical URL, package id hoặc semantic lõi của Patient, Encounter, Condition, Observation.
  • Patch thuần additive: bên triển khai đang dùng 0.5.2 chỉ cần refresh package/download artifact; không có migration dữ liệu bắt buộc.
  • Toàn bộ 10 artifact core-bound mới (4 CodeSystems + 4 ValueSets + 1 extension + 1 ví dụ) nằm trong hl7.fhir.vn.core.base; các gói mô-đun phái sinh (bhyt, terminology.clinical, traditional-medicine, device) không đổi số lượng.
  • VNCoreExtOrgLifecycleRelation và terminology kèm theo là phần mở rộng tùy chọn (0..*), không phá vỡ instance Organization hiện hành.

Phiên bản 0.5.2 — Draft for Community Review Patch (2026-05-29)

Trạng thái: Lịch sử — additive legal-corpus patch trên nền 0.5.1

Ảnh chụp phát hành

  • 52 hồ sơ, 44 phần mở rộng cục bộ + 3 chuẩn HL7, 71 CodeSystems, 77 ValueSets, 5 ConceptMaps
  • 19 SearchParameters, 25 NamingSystems, 13 logical models, 3 OperationDefinitions, 5 CapabilityStatements
  • 156 tệp ví dụ / 158 thực thể ví dụ, 301 total instances, 486 exported JSON artifacts
  • VNLegalDocumentRefCS mở rộng lên 116 concepts (registry máy đọc); registry public giai đoạn v0.5 có 101 mục nguồn TVPL exact; trạng thái public hiện hành của v0.6.0 là 132 nguồn; actionable legal citation coverage giữ 73/73 direct-technical documents (100%)

Nội dung patch

  • Mở rộng VNLegalDocumentRefCS lên 116 concepts: thêm Luật Dân số 113/2025/QH15 (future-effective 01/07/2026), TT 11/2026/TT-BYT, nhóm QĐ triển khai EMR/Sổ sức khỏe điện tử (QĐ 31, QĐ 586, QĐ 965), cặp thay thế dự kiến chi BHYT (QĐ 582 thay QĐ 32) và TTHC KCB (QĐ 966 thay QĐ 658), quy trình kỹ thuật (QĐ 486 YHCT, QĐ 622 điện quang) và các VBHN hợp nhất.
  • Thêm VNFetalSexDisclosureDiseaseVS — 137 dòng STT / 136 mã ICD-10 unique danh mục bệnh được phép tiết lộ giới tính thai nhi theo khoản 3 Điều 6 Luật Dân số 113/2025 và Danh mục TT 11/2026, gắn căn cứ pháp lý qua VNCoreExtLegalBasis.
  • Bổ sung triplet bằng chứng trạng thái (statusReviewedAt/statusEvidenceUrl/statusEvidenceNote) cho QĐ 4905/2019 và QĐ 5937/2021; làm rõ relationshipNote của QĐ 486/2026 (quy trình kỹ thuật YHCT).
  • Đồng bộ governance surface (release-manifest, roadmap, release-metrics, content-facts, wiki inventory, legal-corpus) theo 0.5.2.

Tác động nâng cấp

  • Không đổi canonical URL, package id hoặc semantic lõi của Patient, Encounter, Condition, Observation.
  • Patch thuần additive: bên triển khai đang dùng 0.5.1 chỉ cần refresh package/download artifact; không có migration dữ liệu bắt buộc.
  • VNFetalSexDisclosureDiseaseVS là terminology công bố độc lập (chưa bind vào element profile), dùng để tham chiếu và ràng buộc theo nhu cầu triển khai.

Phiên bản 0.5.1 — Draft for Community Review Patch (2026-05-10)

Trạng thái: Lịch sử — consistency/governance patch trên nền 0.5.0

Ảnh chụp phát hành

  • 52 hồ sơ, 44 phần mở rộng cục bộ + 3 chuẩn HL7, 71 CodeSystems, 76 ValueSets, 5 ConceptMaps
  • 19 SearchParameters, 25 NamingSystems, 13 logical models, 3 OperationDefinitions, 5 CapabilityStatements
  • 131 tệp ví dụ / 158 thực thể ví dụ, 298 total instances, 480 exported JSON artifacts
  • VNLegalDocumentRefCS giữ registry pháp lý v0.5 với 101 mục structured; actionable legal citation coverage đạt 72/72 direct-technical documents (100%)

Nội dung patch

  • Đồng bộ VERSION, sushi-config.yaml, publication-request.json, publication/package-list.json, package split, download surface, roadmap, news và wiki theo 0.5.1.
  • Bổ sung governance manifests (release-manifest, roadmap) làm source of truth cho các consumer file.
  • Bổ sung guard và wiki inventory check để giảm drift khi nâng version.
  • Migrate nhóm citation pháp lý còn thiếu để coverage direct-technical không còn orphan actionable.
  • Bổ sung hoặc public surface các ví dụ cho PaymentReconciliation, EndpointBHYT, HealthcareService tuyến xã và breach notification.

Tác động nâng cấp

  • Không đổi canonical URL, package id hoặc semantic lõi của Patient, Encounter, Condition, Observation.
  • Bên triển khai đang dùng 0.5.0 chỉ cần refresh package/download artifact và đọc lại changelog; không có migration dữ liệu bắt buộc.
  • Bên triển khai đang dùng 0.4.0 nên đọc cả mục 0.5.0 bên dưới vì các thay đổi additive/hardening chính nằm ở bản đó.

Phiên bản 0.5.0 — Draft for Community Review (2026-05-01)

Trạng thái: Lịch sử — structured legal references, device/BHYT hardening và pilot readiness

Ảnh chụp phát hành

  • 52 hồ sơ, 44 phần mở rộng cục bộ + 3 chuẩn HL7, 70 CodeSystems, 75 ValueSets, 5 ConceptMaps
  • 19 SearchParameters, 22 NamingSystems, 13 logical models, 3 OperationDefinitions, 5 CapabilityStatements
  • 152 tệp ví dụ / 154 thực thể ví dụ, 294 total instances, 476 exported JSON artifacts
  • VNLegalDocumentRefCS công bố registry pháp lý v0.5 với 101 mục structured theo 18 miền public, kèm trạng thái hiệu lực và quan hệ thay thế
  • Thêm VNLegalDocumentRefCS và VNLegalDocumentRefVS làm registry pháp lý máy đọc được.
  • Thêm VNCoreExtLegalBasis để gắn căn cứ pháp lý ở mức artifact hoặc element.
  • Thêm audit tooling cho citation: kiểm tra future-effective, văn bản đã bị thay thế, inline-only citation và coverage theo artifact.
  • Mở rộng legal corpus giai đoạn v0.5 lên 101 mục, bao gồm nhóm pháp lý 2026 như VBHN 04/06/08, TT 12/2026/BTC, NĐ 233/2025 và các luật/văn bản mới liên quan dữ liệu, an ninh mạng, phòng bệnh và y tế cơ sở.

Profiles mới hoặc được public surface trong v0.5

  • VNCorePaymentReconciliation — quyết toán/thanh toán BHYT theo chu kỳ và biên bản 06/BH, dùng claimAuditStatus để biểu diễn vòng đời giám định nội địa.
  • VNCoreEndpointBHYT — endpoint cổng gdbhyt cho lớp gateway/facade BHYT.
  • VNCoreHealthcareService — dịch vụ y tế, đặc biệt cho TYT cấp xã/phường/đặc khu sau mô hình chính quyền 2 cấp.
  • VNCoreCompositionBreachNotification — Composition structured cho Mẫu 08 NĐ 356/2025 về thông báo vi phạm DLCN.

Device cluster hardening

  • Thêm VNCoreExtDeviceRegistrationNumber và VNMedicalDeviceRegistrationNumberNS cho số lưu hành TBYT.
  • Gia cố VNCoreImplantableDevice: risk class, số lưu hành, UDI carrier và lifecycle được nâng mức kỳ vọng cho thiết bị cấy ghép C/D.
  • Bổ sung ví dụ thiết bị class A/B/C: ExampleDeviceVTYTN03Syringe, ExampleDeviceVTYTClassBThermometer, ExampleDeviceImplantDentalClassC.
  • Giữ danh pháp thiết bị trong package .device; Core không hard-bind Device.type vào một danh mục duy nhất khi governance danh pháp chưa ổn định.

Tác động nâng cấp

  • Bản 0.5.0 là additive/hardening release: không đổi canonical URL, không đổi package id, không thay thế semantics lõi của Patient, Encounter, Condition, Observation.
  • Bên triển khai đang dùng 0.4.0 nên ưu tiên rà lại device identifiers, legal citation, BHYT reconciliation/gateway boundary và privacy incident/audit policy trước khi pilot.

Phiên bản 0.4.0 — Wave 2 (2026-04-14)

Trạng thái: Draft for Community Review — bổ sung lớp CĐHA, Dược, Thiết bị và Khoa phòng

Ảnh chụp phát hành

  • 48 hồ sơ (thêm 7), 34 phần mở rộng cục bộ + 3 chuẩn HL7, 64 CodeSystems, 69 ValueSets, 4 ConceptMaps
  • 145 tệp ví dụ / 146 thực thể ví dụ, 274 total instances trong release metrics; sushi . import 274 FSH instances

Profiles mới (7)

  • VNCoreOrganizationDepartment — Khoa/Phòng theo QĐ 2010/QĐ-BYT (19/6/2025) Phụ lục 6; identifier slicing departmentCode (K01-K53, K99) + localCode; type fixed dept; partOf bắt buộc tham chiếu CSYT chủ quản
  • VNCoreMedicationDispense — Cấp phát thuốc, liên thông BHYT chain qua authorizingPrescription → VNCoreMedicationRequest
  • VNCoreImagingStudy — Nghiên cứu CĐHA (DICOM StudyInstanceUID); procedureCode/reasonCode/bodySite bindings cho ICD-10 VN + SNOMED CT VN Body Structure
  • VNCoreDiagnosticReportLab, VNCoreDiagnosticReportImaging, VNCoreDiagnosticReportPathology — 3 sub-profiles kế thừa VNCoreDiagnosticReport theo pattern parent-child kiểu JP Core; category slice theo coding.code (LAB/RAD/PAT) + nhóm chi phí BHYT (QĐ 697 nhóm 3/4)
  • VNCoreImplantableDevice — Thiết bị cấy ghép patient-bound theo pattern US Core; patient/type/status 1..1, UDI/lifecycle/safety MS, không hard mandate UDI toàn Core

Refactor trọng tâm

  • VNCoreDevice: nâng từ 2 MS → 12+ MS với identifier slicing (medicalDeviceItemCode, serialNumber), UDI carrier theo FHIR base, full lifecycle (manufactureDate/expirationDate/lotNumber/serialNumber/modelNumber), extension VNCoreExtDeviceGroup fallback và VNCoreExtDeviceRiskClass optional; dữ liệu thanh toán TBYT ưu tiên ở Claim.item; type được relax về 0..1 MS để không reject dữ liệu legacy/BHYT thiếu danh pháp chuẩn
  • VNCoreProcedure: bổ sung focalDevice Must Support cho thủ thuật đặt/tháo/thay/điều chỉnh thiết bị; example PCI đặt stent và tháo lưới lọc tĩnh mạch chủ dùng Procedure.focalDevice, còn theo dõi đang sử dụng dùng DeviceUseStatement
  • VNCoreDiagnosticReport: trở thành parent profile với category slicing open on coding.code; result relax xuống Observation base để children re-tighten
  • ExampleDeviceImplant đổi sang VNCoreImplantableDevice cho Stent mạch vành (SCT 360046005) + deviceGroup N06.00.000, có patient/lifecycle/UDI HRF; bổ sung ExampleDeviceImplantIVCFilter và ExampleProcedureIVCFilterRemoval cho ca explant hợp lý về mặt lâm sàng

Extensions mới (2)

  • VNCoreExtDeviceGroup — Nhóm thiết bị y tế theo danh mục BHYT (N01-N09); Context: Claim.item ưu tiên và Device legacy/fallback; binding extensible VNDeviceGroupVS
  • VNCoreExtDeviceRiskClass — Phân loại rủi ro A/B/C/D theo NĐ 98/2021/NĐ-CP Điều 4 và TT 05/2022/TT-BYT; optional trên Device, không thay nhóm BHYT hoặc Device.type

Terminology mới và cập nhật

  • VNDeviceGroupCS + VNDeviceGroupVS — 9 codes N01.00.000..N09.00.000 theo TT 04/2017/TT-BYT Phụ lục 01 + TT 24/2025/TT-BYT (đổi thuật ngữ VTYT → TBYT) + VBHN 14/VBHN-BYT
  • VNDeviceRiskClassCS + VNDeviceRiskClassVS — 4 codes A..D theo NĐ 98/2021/NĐ-CP Điều 4; dùng cho risk class optional, không dùng làm danh pháp thiết bị
  • VNMedicalDeviceNomenclatureCS + VNMedicalDeviceNomenclatureVS + VNDeviceTypeVS — 956 concept danh pháp thiết bị trong package hl7.fhir.vn.device, tổng hợp QĐ-3107/QĐ-BYT-2024 và QĐ-847/QĐ-BYT-2025 theo provenance concept-level; Core không required-bind Device.type
  • VNExaminationCodeCS — fragment 2 mã khám bệnh dùng cho positive seed XML3, có provenance từ Phụ lục 2 QĐ 2010/QĐ-BYT; hiện cover 02.05 cho Nội tiêu hóa và 10.22 cho Ngoại tiêu hóa, còn 2 row consultation/care chưa đủ sạch vẫn giữ ở catalog ví dụ cục bộ riêng.
  • VNBedDayCodeCS — fragment 2 mã ngày giường dùng cho positive seed XML3, có provenance từ Phụ lục 3 QĐ 2010/QĐ-BYT; hiện cover K22.NG1 và K48.HSTC, trong khi 2 row consultation/care chưa đủ sạch vẫn giữ ở catalog ví dụ cục bộ riêng.
  • VNBHYTFinancialFieldCS + VNBHYTFinancialFieldVS — 14 trường tổng tiền BHYT (T_TONGCHI, T_BHTT, T_BNCCT, T_BNTT, T_NGUONKHAC*, T_NGOAIDS, T_THUOC, T_VTYT) làm source traceability cho cost summary/adjudication.
  • VNBHYTAdjudicationCategoryCS + VNBHYTAdjudicationCategoryVS — 5 category cục bộ (patient-self-pay, other-fund, non-covered, medication-subtotal, supplies-subtotal) để bổ sung HL7 adjudication ở ClaimResponse.total/EOB.total.
  • ConceptMap/vn-cm-bhyt-financial-field-to-adjudication — ánh xạ trường tổng tiền BHYT sang HL7 adjudication và category cục bộ; không encode công thức quyền lợi hoặc catalog lý do từ chối của payer.
  • VNMorphologyVS — Subset SNOMED CT filter concept is-a #49755003 (Morphologically abnormal structure) theo QĐ 2493/QĐ-BYT (08/2025) ~5.155 codes; dùng cho VNCoreDiagnosticReportPathology.conclusionCode extensible binding
  • VNDepartmentCS: 51 → 54 codes (thêm K51 Đột quỵ, K52 Phẫu thuật tạo hình thẩm mỹ, K53 Nam học) per QĐ 2010/QĐ-BYT Phụ lục 6 (tiền nhiệm QĐ 5937/QĐ-BYT bị bãi bỏ phần Phụ lục 5)

Cơ sở pháp lý bổ sung

  • Thiết bị y tế: TT 04/2017/TT-BYT Phụ lục 01, TT 24/2025/TT-BYT (30/6/2025, HL 01/9/2025), VBHN 14/VBHN-BYT
  • Khoa/Phòng: QĐ 2010/QĐ-BYT (19/6/2025) Phụ lục 6, QĐ 3176/QĐ-BYT (MA_KHOA trong XML đầu ra KCB)
  • Dược: Luật 105/2016/QH13 Điều 74 (sửa đổi bởi Luật 44/2024/QH15 Điều 1 khoản 36), NĐ 163/2025/NĐ-CP (29/6/2025, thay NĐ 54/2017 từ 01/7/2025), TT 26/2025/TT-BYT (Điều 5/10/12 — đơn điện tử, liên thông Hệ thống đơn thuốc QG), TT 27/2025/TT-BYT (thuốc YHCT BHYT)
  • Danh mục kỹ thuật và CĐHA/GPB: QĐ 1227/QĐ-BYT (11/4/2025) — 2.964 mã CLS 5 nhóm (HH-TM 1.022, Hóa sinh 447, Vi sinh 174, GPB 81, Điện quang 1.240); TT 23/2024/TT-BYT (thay TT 43/2013 từ 18/10/2024); TT 38/2024/TT-BYT — Hệ thống thông tin KCB; QĐ 697/QĐ-BYT (19/3/2026) — 12 nhóm chi phí; QĐ 2427/QĐ-BYT + QĐ 2493/QĐ-BYT — SNOMED CT VN Body Structure + Morphology; QĐ 3148/QĐ-BYT (2017) — liên thông công nhận KQXN

Văn bản đánh dấu legacy / hết hiệu lực

  • NĐ 54/2017/NĐ-CP — hết hiệu lực 01/7/2025 (thay bởi NĐ 163/2025/NĐ-CP Điều 129)
  • TT 43/2013/TT-BYT — hết hiệu lực 18/10/2024 (thay bởi TT 23/2024/TT-BYT); chapter mapping chính xác cho backward audit: Ch. XVIII = CĐHA, Ch. XXI = TDCN, Ch. XXIV = Vi sinh, Ch. XXV = GPB

Quản trị thiết kế (Design Decisions v0.4)

  • DD-v04-05 — DiagnosticReport sub-profiles (pattern parent-child)
  • DD-v04-06 — Device refactor (identifier slicing + UDI + deviceGroup)
  • DD-v04-07 — Missing Profiles (OrgDept + MedDispense + ImagingStudy)
  • ADR-0005 — VNCoreDevice.type 0..1 MS, chưa required binding danh pháp thiết bị
  • ADR-0007 — thêm VNCoreImplantableDevice patient-bound
  • wave2-legal-consolidated — tổng hợp 3 Codex legal cross-reviews (nguồn: governance/v0.4-decisions/)

Phiên bản 0.3.0 — Bản ổn định trước thí điểm (03/2026)

Trạng thái: Draft for Community Review — bản lịch sử trước Wave 2

Ảnh chụp phát hành

  • 32 hồ sơ, 27 phần mở rộng cục bộ + 3 phần mở rộng Patient chuẩn HL7, 52 CodeSystems, 54 ValueSets
  • 14 SearchParameters, 19 NamingSystems, 13 logical models, 3 OperationDefinitions
  • 122 tệp ví dụ / 123 thực thể ví dụ
  • 232 thực thể / 345 tài nguyên JSON xuất ra sau sushi .

Tài nguyên mới hoặc bổ sung trọng tâm

  • Profiles: VNCoreBundle, VNCoreBHYTSubmissionBundle, VNCoreConsent, VNCoreComposition, VNCoreAuditEvent, VNCoreProvenance, VNCoreRelatedPerson
  • Gia cố lớp hành chính: thêm VNCoreLocation để tách khoa/phòng/địa điểm cung cấp dịch vụ khỏi Organization
  • Gia cố quy trình xét nghiệm: thêm VNCoreSpecimen, nối chuỗi ServiceRequest -> Specimen -> ObservationLab -> DiagnosticReport, bổ sung ví dụ mẫu huyết thanh, máu toàn phần, nước tiểu và tình huống xét nghiệm đầu-cuối
  • Hướng dẫn Must Support: thêm trang must-support-guidance.md, chốt cách diễn giải Must Support, bảng xử lý thiếu dữ liệu và cẩm nang HIS -> FHIR cho bệnh nhân, lượt khám, tài liệu, BHYT và hồ sơ thanh toán
  • Ma trận pháp lý theo miền: thêm mục Ma trận pháp lý theo hồ sơ trong legal-basis.md, tách lớp căn cứ hiện hành / lịch sử / quyết định thiết kế cho 4 nhóm hồ sơ chính: Patient/RelatedPerson, Practitioner/Organization/Location, tài liệu lâm sàng và lớp liên thông hồ sơ BHYT (BHYT Submission)
  • Kiến trúc gói phát hành: thêm trang package-architecture.md, chốt mô hình 4 gói mô-đun (core.base, bhyt.submission, terminology.clinical, terminology.traditional-medicine) và 1 gói tổng hợp
  • Tách gói phát hành: mở rộng cơ chế build để sinh hl7.fhir.vn.core, hl7.fhir.vn.core.base, hl7.fhir.vn.bhyt.submission, hl7.fhir.vn.terminology.clinical và hl7.fhir.vn.terminology.traditional-medicine từ cùng một kho mã nguồn biên soạn
  • Hồ sơ công bố mô-đun: bổ sung package-list.json, history.html, và trang đích công bố tối thiểu cho từng gói mô-đun ngay trong cùng website fhir.hl7.org.vn/core
  • Gia cố template phát hành: chuyển nền HTML build từ fhir.base.template sang fhir2.base.template theo thông báo bảo mật ngày 17/03/2026 của FHIR Foundation, loại bỏ phụ thuộc vào template cũ đã ngừng hỗ trợ
  • Chuẩn hóa Patient: VNCorePatient chuyển sang dùng các extension chuẩn patient-religion, patient-citizenship, patient-birthPlace; thêm các lát cắt BHXH, GKS, HC và contact cho luồng người giám hộ
  • Chuẩn hóa Coverage: thêm subscriber, relationship, invariant kiểm tra subscriberId khớp identifier[BHYT], và đưa Coverage.type về ngữ nghĩa chuẩn FHIR medical thay vì dùng cho NGUON_CTRA
  • Liên thông tôn giáo: thêm ConceptMap vn-cm-religion-to-v3-religious-affiliation và ví dụ mã kép cho patient-religion ở các trường hợp có ánh xạ 1-1
  • Gia cố Consent: thêm invariant yêu cầu provision.period.end khi đã khai báo consent có thời hạn
  • SearchParameters: vn-ma-lk, vn-ma-luot-kcb, vn-ma-dkbd, vn-bhxh, vn-gks, vn-gphn, cùng artifact lịch sử vn-vneid ở trạng thái retired
  • NamingSystems: thêm VNeID (integration-only / retired), GKS, GPHN, VNMaLuotKCB, mã phản hồi gateway BHYT, cùng các hệ CMND/BHXH/Hộ chiếu/Mã vật tư
  • Gia cố định danh Encounter: vn-ext-encounter-code chuyển từ string sang Identifier, gắn system riêng cho MA_LUOT_KCB và đổi vn-sp-encounter-ma-luot-kcb sang token để tìm kiếm nhất quán hơn trong gateway và validator
  • Ví dụ bệnh nhân nước ngoài dùng hộ chiếu: thêm ExamplePatientForeignPassport để minh họa bệnh nhân người nước ngoài dùng identifier[HC], giữ lát cắt CCCD với data-absent-reason, và không lạm dụng forceMajeureReason
  • Artifact gateway layer: Check-in + các logical model BHYT XML 1-12, $validate-bhyt-claim, $submit-bhyt-claim, $reverse-bhyt-claim
  • Gia cố ánh xạ BHYT: thêm chú thích mapping nội tuyến cho toàn bộ logical model Check-in + XML1-12, chốt nguồn FHIR cho từng trường và tách rõ trường gốc với trường suy ra để xuất dữ liệu
  • Làm dày XML2 thuốc BHYT: thêm VNCoreExtPaymentSource cho NGUON_CTRA, sửa đúng semantics VNPaymentSourceCS theo QĐ 130/QĐ 3176 (1 BHYT, 2 dự án/viện trợ, 3 chương trình mục tiêu quốc gia, 4 nguồn khác), và kéo thêm SO_DANG_KY/NGAY_YL vào round-trip/report từ carrier thuốc thực tế
  • Tự động hóa quản trị: thêm script kiểm tra mức bảo mật cơ sở, ảnh chụp/diff thuật ngữ và chuyển đổi khứ hồi BHYT JSON/XML
  • Hỗ trợ kiểm tra số định danh cá nhân: thêm VNCitizenIdBirthplacePrefixCS/VS, đóng gói bộ thuật ngữ hỗ trợ kiểm tra 3 số đầu CCCD và đưa TT 17/2024/TT-BCA vào tài liệu tham chiếu pháp lý
  • Báo cáo chuyển đổi khứ hồi: sinh thêm output/bhyt-roundtrip/README.md và output/bhyt-roundtrip/index.html để rà soát độ bao phủ theo bundle/bảng XML
  • Độ bao phủ bộ dữ liệu kiểm thử BHYT: bổ sung bundle dương tính HIV/AIDS và tử vong, làm giàu bundle nội trú và trẻ sơ sinh để round-trip mapper phủ thực tế xml4-12
  • Báo cáo triển khai: thêm trang implementation-reports.md để chuẩn hóa báo cáo thí điểm/ballot
  • Organization/Location legal alignment: tách riêng organizationRank, healthUnitRank, organizationRankStatus, facilityCareLevel, và legacyTechnicalLine; bổ sung trang organization-location-governance.md
  • YHCT terminology semantics: chuẩn hóa CodeSystem.property.uri cho toàn bộ 10 CodeSystem YHCT, giữ nguyên mã pháp lý nhưng làm rõ ngữ nghĩa property trong hệ sinh thái terminology và loại bỏ toàn bộ thông báo QA kiểu “property has only a code and not a URI”
  • Chiến lược biên soạn bộ mã lớn: chuyển các CodeSystem quy mô lớn như VNCLSCS, VNWardCS, VNOCCS và toàn bộ 10 CodeSystem Y học cổ truyền sang tài nguyên FHIR JSON sinh sẵn từ dữ liệu nguồn máy đọc được hoặc phụ lục pháp lý, giúp SUSHI ổn định và giữ nguyên provenance pháp lý
  • Tái cấu trúc định danh người hành nghề: chuyển VNCorePractitioner sang mô hình GPHN hiện hành / CCHN lịch sử, thêm NamingSystem VNGPHN và vn-sp-practitioner-gphn, đồng thời hạ CCHN xuống lớp tương tác liên thông dữ liệu lịch sử

Điều chỉnh sau rà soát lâm sàng

  • CCCD bắt buộc: identifier[CCCD] 0..1 → 1..1 per TT 13/2025
  • security.md: Cập nhật reference VNCoreConsent (thay thế interim guidance)
  • VNProvinceCS: Ghi rõ ^count = 63 (34 active + 29 deprecated)
  • Ví dụ Coverage: Dùng type có mã hóa thay vì chỉ dùng văn bản
  • Guardian modeling: thêm VNCoreRelatedPerson + example mẹ của bệnh nhi; tách riêng example quyền lợi BHYT cấp trực tiếp cho trẻ và example coverage liên kết người đại diện
  • Consent trẻ em: bổ sung thuật ngữ parental-proxy/guardian-consent và ví dụ ExampleConsentParentalProxy dùng RelatedPerson làm người thực hiện đồng ý

Hạ tầng

  • Cloudflare Worker: ghi đè đường dẫn URL (không chuyển hướng) cho canonical FHIR URL
  • Định tuyến theo mẫu: tự nhận diện tất cả resource type
  • Bộ xử lý /core/*: package-list.json, qa.html được phục vụ đúng qua /core/
  • CI: Node.js 22 + runtime Node.js 24 bật theo lựa chọn
  • FHIR auto-ig-builder GitHub App cài đặt

Phiên bản 0.1.0 — Bản dự thảo đầu tiên (03/2026)

Trạng thái: Draft

Profiles (23)

  • VNCorePatient — Bệnh nhân Việt Nam (CCCD, tên tiếng Việt, dân tộc, tôn giáo, nghề nghiệp, địa chỉ 2 cấp)
  • VNCorePractitioner — Nhân viên y tế (CCHN, học vị)
  • VNCorePractitionerRole — Vai trò nhân viên y tế (chức danh V.08, chuyên khoa)
  • VNCoreOrganization — Cơ sở KCB (hạng BV, tuyến, loại hình)
  • VNCoreAddress — Địa chỉ Việt Nam (tỉnh + xã, backward-compatible huyện)
  • VNCoreEncounter — Lượt khám/điều trị (loại KCB BHYT, kết quả điều trị)
  • VNCoreCondition — Chẩn đoán (ICD-10 VN + YHCT)
  • VNCoreObservationLab — Kết quả xét nghiệm (LOINC VN)
  • VNCoreObservationVitalSigns — Sinh hiệu
  • VNCoreObservationYHCT — Quan sát YHCT (lưỡi, mạch, triệu chứng)
  • VNCoreAllergyIntolerance — Dị ứng (SNOMED CT VN)
  • VNCoreProcedure — Thủ thuật/phẫu thuật (ICD-9-CM)
  • VNCoreMedicationRequest — Đơn thuốc điện tử (ePrescription, TT 13/2025, Luật Dược 2016, QĐ 3176)
  • VNCoreMedication — Thuốc (ATC, SNOMED CT)
  • VNCoreServiceRequest — Yêu cầu DVKT/cận lâm sàng (TT 20/2014, TT 39/2018, QĐ 3176)
  • VNCoreCoverage — Thẻ BHYT (3 format: CCCD/BHXH/cũ)
  • VNCoreClaim — Yêu cầu thanh toán KCB BHYT (QĐ 3176 → QĐ 697, 14 nhóm chi phí)
  • VNCoreClaimResponse — Phản hồi thanh toán BHYT
  • VNCoreExplanationOfBenefit — Giải trình quyền lợi BHYT
  • VNCoreDocumentReference — Tài liệu y tế (bệnh án điện tử per TT 13/2025)
  • VNCoreDiagnosticReport — Kết quả CLS (XN, CĐHA, GPB)
  • VNCoreDevice — Trang thiết bị y tế
  • VNCoreDeviceUseStatement — Sử dụng TBYT cho bệnh nhân

Extensions (20)

  • vn-ext-ethnicity — Dân tộc (54 dân tộc, 121/TCTK-PPCĐ)
  • vn-ext-religion — Tôn giáo (16 tôn giáo, CV 6955/BNV-TGCP)
  • vn-ext-occupation — Nghề nghiệp (VSCO 2020, 1.516 mã, QĐ 34/2020/QĐ-TTg)
  • vn-ext-province — Tỉnh/TP (34 đơn vị, NQ 202/2025)
  • vn-ext-ward — Xã/Phường (~3.321 đơn vị, NQ 202/2025)
  • vn-ext-bhyt-card-type — Loại đối tượng BHYT (53 mã, NĐ 146/2018)
  • vn-ext-primary-care-facility — Nơi ĐKKCB ban đầu (Luật BHYT)
  • vn-ext-insurance-visit-type — Loại KCB BHYT (MALYDO, QĐ 3176)
  • vn-ext-treatment-outcome — Kết quả điều trị (KET_QUA_DTRI, 8 mã, QĐ 3176)
  • vn-ext-org-rank — Hạng bệnh viện (4 hạng, TT 06/2024/TT-BYT)
  • vn-ext-org-level — Tuyến KCB
  • vn-ext-org-type — Loại hình CSKCB (8 loại, Luật KCB 2023)
  • vn-ext-claim-cost-summary — Tổng hợp chi phí Claim (QĐ 697)
  • vn-ext-claim-item-department — Khoa chỉ định dịch vụ
  • vn-ext-claim-payment-period — Thời gian thanh toán BHYT
  • vn-ext-insurance-cost-info — Thông tin chi phí BHYT
  • vn-ext-payment-method — Phương thức thanh toán
  • vn-ext-order-date — Ngày y lệnh
  • vn-ext-med-registration-number — Số đăng ký thuốc
  • vn-ext-device-insurance-scope — Phạm vi BH trang thiết bị y tế

CodeSystems (42) và ValueSets (43)

  • 17 CodeSystem quốc gia (dân tộc, tôn giáo, ĐVHC, BHYT 53 mã, KCB, chi phí 14 mã, kết quả điều trị 8 mã, ra viện 5 mã, mã đối tượng KCB 27 mã per QĐ 3276, loại dịch vụ y tế 8 mã per TT 20/2014 + TT 39/2018, trình độ chuyên môn, v.v.)
  • 2 CodeSystem nhân viên y tế:
    • Chức danh nghề nghiệp V.08 (32 mã — TT 41/2025, TT 02/2025)
    • Chuyên khoa y tế (47 mã, 8 nhóm — TT 43/2013 DMKT 28 chuyên khoa, TT 21/2017, TT 32/2023 Điều 11 Phụ lục V–XVII)
  • 5 CodeSystem quốc tế bản địa hóa (ICD-10 VN 15.026, ICD-9-CM 3.882, SNOMED CT VN 77.393, LOINC VN 66.077, CLS VN 2.964)
  • 10 CodeSystem Y học cổ truyền (QĐ 2552 + QĐ 3080) — bao gồm VNYHCTDiseaseCS 228 mã (38 bệnh danh + 190 thể lâm sàng)
  • 7 CodeSystem bảo hiểm/thanh toán (chi phí, phương thức TT, phạm vi BH TBYT, loại CLS, per QĐ 697/QĐ-BYT)
  • 1 CodeSystem nghề nghiệp VSCO (1.516 mã, 5 cấp, ISCO-08 compatible — QĐ 34/2020/QĐ-TTg)

SearchParameters (11)

  • vn-sp-patient-cccd — Tìm Patient theo CCCD (Luật Căn cước 2023)
  • vn-sp-patient-bhyt — Tìm Patient theo BHYT (Luật BHYT)
  • vn-sp-organization-cskcb — Tìm Organization theo mã CSKCB (QĐ 3176)
  • vn-sp-practitioner-cchn — Tìm Practitioner theo CCHN (Luật KCB 2023, Điều 19-26)
  • vn-sp-coverage-bhyt — Tìm Coverage theo số thẻ BHYT (NĐ 188/2025)
  • vn-sp-encounter-malydo — Tìm Encounter theo MALYDO (QĐ 3176/QĐ-BYT)
  • vn-sp-condition-icd10 — Tìm Condition theo ICD-10 (QĐ 4469/QĐ-BYT, QĐ 98/QĐ-BYT)

ConceptMaps (2)

  • vn-cm-cls-to-loinc — Ánh xạ CLS VN → LOINC (2.964 chỉ số, 100% coverage, QĐ 1227/QĐ-BYT)
  • vn-cm-religion-to-v3-religious-affiliation — Ánh xạ một phần danh mục tôn giáo Việt Nam sang v3-ReligiousAffiliation cho các trường hợp tương đương rõ về ngữ nghĩa

CapabilityStatement (5)

  • VNCoreServer — CapabilityStatement mức cơ sở cho máy chủ FHIR tuân thủ VN Core
  • VNCoreEMRServer — CapabilityStatement mức cơ sở cho EMR/EHR nội bộ
  • VNBHYTGatewayClient — CapabilityStatement mức cơ sở cho client gửi hồ sơ thanh toán BHYT
  • VNBHYTGatewayServer — CapabilityStatement mức cơ sở cho server/facade tiếp nhận hồ sơ thanh toán BHYT
  • VNCitizenAppClient — CapabilityStatement mức cơ sở cho ứng dụng người dân/VNeID connector

NamingSystems (5)

  • CCCD, BHYT, CCHN, CSKCB, MRN

Examples (33)

  • Ít nhất 1 ví dụ cho mỗi profile
  • 2 ví dụ Patient (đầy đủ + tối thiểu)
  • 2 ví dụ Practitioner (BSCKII + tối thiểu) + 1 PractitionerRole
  • 2 ví dụ Organization (BV tuyến TW + Trạm y tế)
  • 2 ví dụ Coverage (BHYT mới + legacy)
  • 2 ví dụ Encounter (ngoại trú + nội trú)
  • 4 ví dụ Condition (Tây y + YHCT)
  • 1 ví dụ MedicationRequest + 1 Medication
  • 2 ví dụ ServiceRequest (xét nghiệm đường huyết + chụp X-quang ngực)
  • 1 ví dụ Claim + 1 ClaimResponse + 1 ExplanationOfBenefit
  • 1 ví dụ DocumentReference + 1 DiagnosticReport
  • 1 ví dụ Device + 1 DeviceUseStatement
  • Các ví dụ Observation (Lab, VitalSigns, YHCT), AllergyIntolerance, Procedure, Address

Cải tiến đáng chú ý

  • VNYHCTDiseaseCS — REBUILD HOÀN TOÀN từ Excel nguồn QĐ 2552/QĐ-BYT (sheet "DM ngay 2752025"):
    • Sửa lỗi nghiêm trọng: U50.101 trước đó ghi sai bệnh danh ("Hiếp thống" → đúng: "Hoàng đản")
    • Sửa format sub-code: từ .0, .1, .8, .9 (sai) → .01, .02, .03... (đúng QĐ 2552)
    • Tăng từ 135 codes (sai, thiếu) → 228 codes (38 bệnh danh + 190 thể lâm sàng)
    • Bổ sung 12 bệnh danh thiếu: Hoàng đản, Si ngốc, Si chứng, Thất ngôn, Tọa cốt phong, Tọa điến phong, Kiên tý, Khái thấu, Chứng cam, Phong chẩn, Tầm ma chẩn, Hạ trĩ
    • 228/228 display duy nhất — không còn trùng lặp (trước đó 25 nhóm display giống hệt)
    • Display bệnh danh: "{YHCT} — {YHHĐ} [{ICD-10}]" (VD: "Yêu thống — Đau cột sống thắt lưng [M54.5]")
    • Display thể lâm sàng: "{YHCT}: {tên thể} [{ICD-10}]" (VD: "Yêu thống: Thể hàn thấp [M54.5]")
    • hierarchyMeaning sửa từ #grouped-by → #is-a (chuẩn FHIR)
    • Properties mới: icd10 (mã ICD-10), yhhd-name (tên bệnh YHHĐ), ma-dung-chung (mã dùng chung BYT)
    • English designations đầy đủ cho 228 codes (thuật ngữ TCM chuẩn quốc tế)
  • VNCoreServiceRequest — Bổ sung 3 elements:
    • identifier (0..* MS) — Mã phiếu chỉ định / Số yêu cầu
    • requisition (0..1) — Mã nhóm yêu cầu (gộp nhiều XN/DVKT cùng phiếu)
    • performerType (0..1) — Loại chuyên khoa thực hiện, bind VNSpecialtyVS
    • Cập nhật code description: ghi rõ LOINC cho XN (QĐ 1227), ICD-9-CM cho PT/TT (QĐ 387), SNOMED CT cho CĐHA
  • ExampleConditionYHCTYeuThong — Cập nhật dùng mã thể lâm sàng cụ thể U62.392.5.01 (Thể hàn thấp) thay vì base code U62.392.5

Trang nội dung (16)

  • Trang chủ, Giới thiệu (Omi HealthTech & OmiGroup), Bắt đầu nhanh
  • Cơ sở pháp lý, Hướng dẫn chung, Hướng dẫn thuật ngữ
  • Tình huống lâm sàng (khám ngoại trú + BHYT)
  • Profiles, Extensions, Thuật ngữ, Bảo mật
  • Validation, Ổn định & Conformance, SNOMED CT VN Đính chính
  • Tải xuống, Lịch sử thay đổi

Khung pháp lý tham chiếu

  • 28+ văn bản pháp lý và chiến lược liên quan (NQ 202/2025, TT 13/2025, Luật 91/2025, NĐ 356/2025, QĐ 3516/QĐ-BYT, v.v.)
  • Tuân thủ mô hình ĐVHC 2 cấp mới (34 tỉnh + xã)
  • Tuân thủ Luật BVDLCN (dữ liệu y tế = DLCN nhạy cảm)

Liên hệ với các trang khác

Nếu cần Nên đọc tiếp
Tìm hiểu quy trình phát hành và governance của IG Release & Governance
Hiểu chiến lược ổn định và cam kết backward-compatibility Stability & Conformance
Tải xuống phiên bản hiện hành và các artifact liên quan Downloads

English Summary

This changelog records VN Core release deltas. Read the 0.6.0 entry first for current release impacts: release metadata, package surface, roadmap/news/wiki, and legal citation coverage. 0.5.0 remains the main additive/hardening note; older entries are historical.