Hướng dẫn triển khai FHIR cốt lõi Việt Nam — VN Core FHIR Implementation Guide - Draft for Community Review (v0.10.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Hướng dẫn thuật ngữ

Hướng dẫn thuật ngữ — Terminology Guidance

Cách dùng terminology trong VN Core FHIR IG, gồm CodeSystem, ValueSet, provenance pháp lý, ranh giới gói và nguyên tắc phối hợp giữa mã quốc gia với mã quốc tế.

Thuật ngữ quốc tế trước, danh mục Việt Nam sau

VN Core hiện tại đi theo mô hình kết hợp thuật ngữ quốc tế với danh mục Việt Nam, thay vì chọn một phía và loại bỏ phía còn lại. Hướng này được giữ lại nhưng quản trị được siết chặt hơn:

• Ưu tiên LOINC, SNOMED CT, ICD và các bộ mã quốc tế khi chúng đã đáp ứng đúng bài toán;
• Localize hoặc bổ sung bằng bộ mã Việt Nam khi có căn cứ pháp lý, nhu cầu vận hành hoặc khoảng trống ngữ nghĩa thật;
• Quản lý provenance pháp lý và ranh giới gói của từng bộ mã ngay từ đầu, không để terminology đứng ngoài chiến lược bề mặt công bố.

Nguyên tắc quản trị

• Không mở rộng scope chỉ vì một danh mục từng tồn tại trong nguồn cũ.
• Không trộn bộ mã nền tảng với bộ mã lớn, biến động cao mà không có chiến lược phát hành riêng.
• Không coi CodeSystem và ValueSet là danh mục tách rời implementation guidance, search, validation và package quản trị.

Nguyên tắc chung

CodeSystem vs ValueSet

Song ngữ

VN Core ưu tiên display tiếng Việt và designation tiếng Anh khi có bản dịch được quản trị; mức bao phủ song ngữ được công bố theo từng CodeSystem, không mặc định là 100%:

• display = Tiếng Việt (ngôn ngữ chính)
• designation[en] = Tiếng Anh (khi có)

{
  "code": "01",
  "display": "Kinh",
  "designation": [{
    "language": "en",
    "value": "Kinh (Vietnamese)"
  }]
}

Mô hình biên soạn các bộ mã lớn

VN Core hiện dùng hai cách biên soạn thuật ngữ song song:

• FSH cho các bộ mã nhỏ hoặc cần biên tập thủ công nhiều về mô tả, designation và ràng buộc nghiệp vụ.
• Tài nguyên FHIR JSON sinh sẵn cho các bộ mã quy mô lớn, có dữ liệu nguồn máy đọc được và cần giữ ổn định tuyệt đối theo phụ lục pháp lý.

Các bộ mã đang đi theo hướng tài nguyên JSON sinh sẵn gồm:

• VNCLSCS
• VNWardCS
• VNOCCS
• Toàn bộ 10 CodeSystem Y học cổ truyền (VNYHCTDiseaseCS, VNYHCTDiagnosisCS, VNYHCTAcupointCS, VNYHCTTechniqueCS, VNYHCTSymptomCS, VNYHCTTongueCS, VNYHCTPulseCS, VNYHCTTreatmentMethodCS, VNYHCTHerbCS, VNYHCTPrescriptionCS)
• VNMedicalDeviceNomenclatureCS trong package hl7.fhir.vn.device

Cách làm này giúp:

• Giữ nguyên dữ liệu nguồn và provenance pháp lý;
• Giảm thời gian biên dịch SUSHI;
• Tăng khả năng tái lập giữa môi trường phát triển, kiểm tra và phát hành.

Các nhóm thuật ngữ

Thuật ngữ quốc gia — do VN Core định nghĩa

Các CodeSystem đặc thù Việt Nam, không có tương đương quốc tế:

Thuật ngữ y khoa quốc tế — bản địa hoá cho VN

Edition ICD-10 2026 — đã rebuild và đối soát (07/08/2026): danh mục dựng trực tiếp từ bảng 29 cột trong phụ lục ban hành kèm TT 06/2026/TT-BYT (bản PDF ký, 1.275 trang — nguồn công bố tại Cổng Chính phủ), mang đủ sáu cờ sử dụng WHO 2019 và hướng dẫn mã hoá song ngữ cho toàn danh mục. Đối soát ba chiều bằng scripts/reconcile_icd10_edition.py: tập mã bảng TT 06 khớp đúng chuỗi (bảng QĐ 4469/QĐ-BYT − Phụ lục 4 + Phụ lục 5 QĐ 1849/QĐ-BYT), 8 phép kiểm R1-R8 sạch; hai phân xử nguồn được khoá cứng trong gate (J13 — PL4 dọn dòng trùng chứ không huỷ mã; M47.00†–M47.09† — bảng TT 06 in dagger trong khi PL5 ký in bare). Bản edition 2020 đóng băng nguyên trạng tại CodeSystem-vn-icd10-cs-2020-legacy.full.json (15.617 concept, version 2020-legacy) cho dữ liệu lập trước 01/07/2026. Quyền tái phân phối vẫn cần chủ sở hữu IG phê duyệt trước khi phát hành production (ghi trong copyright của artifact).

Thuật ngữ Y học cổ truyền (YHCT)

Chỉ số cận lâm sàng (CLS) — QĐ 1227/QĐ-BYT

Bộ Y tế ban hành bộ mã CLS quốc gia (QĐ 1227/QĐ-BYT, 11/04/2025) gồm 2.964 chỉ số. ConceptMap hiện có đích LOINC cho 100% mã nguồn, nhưng đây là độ phủ kỹ thuật của mapping, không phải tuyên bố mọi cặp đều tương đương lâm sàng 1–1: chỉ 1.404/2.964 quan hệ là equivalent, còn 1.560 ở mức wider (đích rộng hơn nguồn) và cần chuyên gia thuật ngữ rà soát trước khi dùng cho quyết định lâm sàng hoặc phân tích.

Ba miền nghiệp vụ — ba ValueSet. QĐ 1227/QĐ-BYT gộp ba miền vào một danh mục; từ 0.10.0 IG tách ValueSet theo miền để binding đúng loại dịch vụ (một kết quả xét nghiệm không được mang mã chụp X-quang):

Artifact VNCLSCS hiện được sinh thành tài nguyên JSON từ dữ liệu nguồn máy đọc được của QĐ 1227/QĐ-BYT trước khi gọi SUSHI. Đây là lựa chọn kiến trúc có chủ đích để vừa bảo toàn mã pháp lý, vừa giữ lượt build ổn định.

Binding strength: từ 0.10.0, VNCoreObservationLab.code bind extensible vào vn-lab-observation-code-vs — ValueSet này gồm cả LOINC và vn-cls-cs (Phụ lục 01–03, miền xét nghiệm) như hai hệ ngang hàng, không phải quan hệ chính–phụ. Mã CLS theo QĐ 1227/QĐ-BYT vì vậy nằm TRONG binding, không phải "mã ngoài dùng khi LOINC không có". Trước 0.10.0 profile bind vào tập chung observation-codes của HL7, khiến 2.964 chỉ số của danh mục quốc gia không ràng buộc được kết quả xét nghiệm nào. Vẫn khuyến nghị gửi song song hai coding để bảo toàn ánh xạ; profile không dùng binding required.

Nguyên tắc coding trong FHIR Observation:

{
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "718-7",
        "display": "Hemoglobin [Mass/volume] in Blood"
      },
      {
        "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-cls-cs",
        "code": "1000151",
        "display": "Lượng huyết sắc tố trong máu"
      }
    ]
  }
}

Không tự động dual-code. Với 1.560 mã có quan hệ wider, hệ thống KHÔNG được tự sinh coding LOINC từ mã CLS như thể tương đương — làm vậy là ghi kết quả thành khái niệm rộng hơn thực tế. Khi cần trao đổi quốc tế cho nhóm này, dùng đích wider kèm ngữ cảnh ConceptMap (equivalence đi cùng), không nhét thẳng vào Observation.code.coding.

5 nhóm CLS:

Nghề nghiệp (VSCO 2020)

Danh mục nghề nghiệp Việt Nam (QĐ 34/2020/QĐ-TTg) gồm 1.516 mã, 5 cấp phân loại. Tương thích ISCO-08 ở Cấp 1-4, Cấp 5 là chi tiết riêng Việt Nam.

Dùng cho Patient.extension hoặc các tài nguyên liên quan nghề nghiệp bệnh nhân.

Danh pháp thiết bị y tế

Danh pháp thiết bị y tế được tách khỏi Core vào package hl7.fhir.vn.device để không hard-bind VNCoreDevice.type khi phạm vi catalog/regulatory còn tiếp tục mở rộng.

Các concept có provenance ở mức từng mã qua sourceDecision, nomenclatureYear, section, sourceRow, sourceStt và status. Khi bổ sung SNOMED CT, GMDN hoặc EMDN, dùng ConceptMap riêng theo license thực tế, không gộp trực tiếp vào CodeSystem Việt Nam.

Binding strength cho mã BHYT đóng

Một số trường trong luồng KCB BHYT có danh mục mã đóng theo quy định (giám định BHXH từ chối mã ngoài danh mục), như Encounter.hospitalization.dischargeDisposition (VNDischargeDispositionVS), Claim.item.category (VNCostCategoryVS theo QĐ 697/QĐ-BYT), ClaimResponse.error.code (VNBHYTProcessingIssueVS — chỉ mã lỗi XỬ LÝ) và ClaimResponse.adjudication.reason (VNBHYTAdjudicationIssueVS — mã kết quả giám định). Hai tập này tách nhau từ 0.10.0 vì ClaimResponse.error trong R4 chỉ dành cho lỗi khiến hồ sơ không giám định được, không phải từ chối nghiệp vụ có căn cứ pháp lý. VNInsuranceVisitTypeVS là danh mục legacy dựa trên MA_LYDO_VVIEN của QĐ 4210/QĐ-BYT (mã 1–4; mã 5 là mở rộng dự án chờ nguồn), không phải danh mục hiện hành của QĐ 3176/QĐ-BYT; triển khai hiện hành dùng MA_DOI_TUONG_KCB qua VNPatientVisitTypeCS.

Quyết định thiết kế có chủ đích: trong VN Core (IG nền) các binding này để extensible, KHÔNG phải required. Lý do:

• Giữ core linh hoạt cho dual-coding (vd kèm SNOMED/ICD), tái sử dụng ngoài ngữ cảnh BHYT, và dữ liệu chuyển tiếp;
• Tránh chặn cứng khi BYT/BHXH cập nhật danh mục giữa các kỳ phát hành.

Việc siết required cho đúng danh mục đóng được thực hiện ở tầng profile/IG vệ tinh BHYT submission (nơi mọi instance phải qua giám định BHXH), không phải ở core. Khi triển khai luồng nộp BHXH, hệ thống PHẢI dùng mã trong ValueSet tương ứng — xem BHYT Submission.

Tóm tắt: extensible ở core = "phải dùng mã trong danh mục nếu có khái niệm phù hợp; chỉ dùng mã ngoài khi danh mục không có khái niệm phù hợp"; required ở IG vệ tinh BHYT = "chỉ chấp nhận mã trong danh mục pháp lý hoặc hợp đồng tích hợp được profile vệ tinh chỉ định".

Cách sử dụng trong profiles

Coding element

{
  "code": {
    "coding": [{
      "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-icd10-cs",
      "code": "J18.9",
      "display": "Viêm phổi, không xác định"
    }]
  }
}

Khi CodeSystem không đủ

Nếu cần mã không có trong ValueSet có binding extensible:

1. Tìm khái niệm có ngữ nghĩa phù hợp trong ValueSet; không chọn mã “gần nhất” nếu khác nghĩa.
2. Nếu không có khái niệm phù hợp, dùng coding từ CodeSystem khác được quản trị, ví dụ SNOMED CT quốc tế.
3. Ghi CodeableConcept.text để bảo toàn diễn giải nguồn khi cần.

{
  "code": {
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "123456789",
      "display": "Some concept"
    }],
    "text": "Mô tả bằng tiếng Việt"
  }
}

Phiên bản thuật ngữ

• CodeSystem.version phải theo chính sách phiên bản của nguồn thuật ngữ; phiên bản gói IG và phiên bản nghiệp vụ của bộ mã được quản trị riêng.
• Khi nguồn ban hành thay đổi, công bố bản mới, trạng thái mã và hướng dẫn chuyển đổi.
• Khi một mã bị tái sử dụng với nghĩa khác, quy tắc mặc định của VN Core là tách canonical hiện hành và canonical -legacy. Coding.system là cơ chế chính để phân biệt identity giữa hai giai đoạn hiệu lực; không được đổi system rồi giữ nguyên code nếu ConceptMap không xác nhận equivalent.
• Họ đơn vị hành chính là ngoại lệ đã ghi trong hợp đồng 0.10.0: mỗi cấp dùng một canonical thống nhất, còn tên, cha và hiệu lực theo ngày chỉ lấy từ state có bằng chứng. Cùng mã/tên không tạo quan hệ chuyển đổi.
• Coding.version là tuỳ chọn. Nếu có, giá trị phải khớp business version của canonical được chọn; không dùng Coding.version để bù cho semantic collision dưới cùng canonical.

English: A meaning change or code-identity reuse normally requires a separate -legacy canonical. Administrative units use the bounded 0.10.0 exception: one canonical per level with evidenced dated states, and no identity or transition is inferred from a matching code or name. Coding.version is optional and, when present, must match the selected canonical's business version.

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

English Summary

This page defines VN Core terminology governance. It explains how Vietnam-specific CodeSystems, localized international terminologies, traditional-medicine terminology, and CLS indicators are published and used, and how CodeSystem, ValueSet, binding strength, and package boundary should be handled consistently. Meaning changes use split current/legacy canonicals; Coding.version is optional and must match the selected canonical when present.