Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.5.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ý, package boundary 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 governance đượ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à package boundary của từng bộ mã ngay từ đầu, không để terminology đứng ngoài chiến lược publication.

Nguyên tắc governance

• 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 governance.

Nguyên tắc chung

CodeSystem vs ValueSet

Song ngữ

Tất cả CodeSystem trong VN Core IG đều hỗ trợ song ngữ Việt-Anh:

• 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/2025

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ố, ánh xạ 100% sang LOINC.

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). Điều này có nghĩa hệ thống NÊN (SHOULD) gửi LOINC code khi có mã phù hợp, nhưng KHÔNG bắt buộc — có thể dùng mã CLS VN hoặc mã nội bộ khi LOINC không đáp ứng. Profile hiện tại chưa bắt buộc (required) LOINC coding.

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.

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 mã gần nhất trong ValueSet
2. Nếu không tìm thấy, sử dụng coding từ CodeSystem khác (ví dụ: SNOMED CT quốc tế)
3. Ghi text mô tả bằng tiếng Việt

{
  "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ữ

• Phiên bản CodeSystem theo format: YYYY.N (ví dụ: 2025.1)
• Khi BYT ban hành danh mục bổ sung/sửa đổi, CodeSystem sẽ được cập nhật
• Hệ thống FHIR nên lưu trữ version của CodeSystem đã sử dụng

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.