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.9.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 hóa cho VN

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: nhiều quan hệ đang ở mức wider/heuristic 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.

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: VNCoreObservationLab.code sử dụng binding extensible đến observation-codes (LOINC). Nếu ValueSet có khái niệm phù hợp, hệ thống phải dùng mã trong ValueSet; chỉ khi không có khái niệm phù hợp mới dùng mã ngoài, chẳng hạn mã CLS Việt Nam. Có thể gửi thêm coding tương đương từ CodeSystem khác để bảo toàn ánh xạ. Profile hiện tại không dùng binding required cho LOINC.

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": "1000001",
        "display": "Định lượng Hemoglobin (Hb)"
      }
    ]
  }
}

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) và ClaimResponse.error.code. 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, VN Core tách canonical hiện hành và canonical -legacy. Coding.system là cơ chế duy nhất để 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.
• Coding.version là tùy 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 requires a separate -legacy canonical. The Coding.system value is the identity boundary. 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.