# Hướng dẫn thuật ngữ - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## 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

| | | |
| :--- | :--- | :--- |
| **CodeSystem** | Định nghĩa bộ mã (codes + display) | `VNEthnicityCS`— định nghĩa 54 mã dân tộc |
| **ValueSet** | Tập hợp con các mã cho một ngữ cảnh cụ thể | `VNEthnicityVS`— include toàn bộ`VNEthnicityCS` |

### 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ế:

| | | | |
| :--- | :--- | :--- | :--- |
| `VNEthnicityCS` | 121/TCTK-PPCĐ | 54 | 54 dân tộc Việt Nam |
| `VNReligionCS` | CV 6955/BNV-TGCP | 16 | 16 tôn giáo được công nhận |
| `VNProvinceCS` | NQ 202/2025 | 34 | 34 tỉnh/TP sau sắp xếp |
| `VNDistrictCS` | Legacy | ~700 | Huyện/quận (deprecated, hỗ trợ dữ liệu cũ) |
| `VNWardCS` | NQ 202/2025 | ~3.321 | Xã/phường/thị trấn |
| `VNIdentifierTypeCS` | VN Core | 11 | Loại định danh VN |
| `VNBHYTCardTypeCS` | BHXH VN | 53 | Loại đối tượng thẻ BHYT |
| `VNHealthcareLevelCS` | NQ 202/2025, Luật TCCQĐP 2025 | 3 | Cấp quản lý hành chính y tế (TW, Tỉnh, Xã) |
| `VNLegacyTechnicalLineCS` | TT 43/2013, TT 23/2024 | 4 | Tuyến chuyên môn kỹ thuật lịch sử (legacy only) |
| `VNHospitalRankCS` | TT 06/2024 | 4 | Hạng pháp lý của cơ sở KCB |
| `VNHealthUnitRankCS` | TT 06/2024 | 4 | Hạng pháp lý của đơn vị y tế không phải cơ sở KCB |
| `VNOrganizationRankStatusCS` | VN Core | 3 | Tình trạng xếp hạng |
| `VNOrganizationTypeCS` | Luật KCB 2023, TT 06/2024 | 10 | Loại hình cơ sở y tế |
| `VNInsuranceVisitTypeCS` | QĐ 3176 | 5 | Loại KCB BHYT (trường MALYDO) |
| `VNDischargeDispositionCS` | QĐ 3176 | 5 | Tình trạng ra viện |
| `VNTreatmentOutcomeCS` | QĐ 3176 | 8 | Kết quả điều trị |
| `VNCostCategoryCS` | QĐ 697/2026 | 14 | Danh mục chi phí KCB |
| `VNQualificationCS` | Luật KCB 2023, NĐ 96/2023 | 14 | Trình độ chuyên môn y tế |

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

| | | | |
| :--- | :--- | :--- | :--- |
| `VNICD10CS` | WHO ICD-10 | QĐ 4469/2020 + QĐ 98/2022 | 15.026 (metadata-only trên IG + full JSON qua downloads) |
| `VNICD9CMCS` | CMS ICD-9-CM V32 | QĐ 387/QĐ-BYT (02/2026) | 3.882 |
| `VNSNOMEDSubsetCS` | SNOMED International | QĐ 2427, 2493, 2805/2025 | 77.393 |
| `VNLOINCCS` | Regenstrief LOINC | QĐ 1227/2025 | 66.077 (metadata-only, deduplicated) |

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

| | | | |
| :--- | :--- | :--- | :--- |
| `VNYHCTDiseaseCS` | QĐ 2552/2025 | 1 | Thể lâm sàng YHCT |
| `VNYHCTDiagnosisCS` | QĐ 2552/2025 | 1 | Chẩn đoán YHCT |
| `VNYHCTAcupointCS` | QĐ 2552/2025 | 1 | Huyệt châm cứu |
| `VNYHCTTechniqueCS` | QĐ 2552/2025 | 1 | Kỹ thuật YHCT |
| `VNYHCTSymptomCS` | QĐ 3080/2025 | 2 | Triệu chứng YHCT |
| `VNYHCTTongueCS` | QĐ 3080/2025 | 2 | Chẩn đoán lưỡi |
| `VNYHCTPulseCS` | QĐ 3080/2025 | 2 | Chẩn đoán mạch |
| `VNYHCTTreatmentMethodCS` | QĐ 3080/2025 | 2 | Pháp điều trị |
| `VNYHCTHerbCS` | QĐ 3080/2025 | 2 | Dược liệu |
| `VNYHCTPrescriptionCS` | QĐ 3080/2025 | 2 | Bài thuốc cổ phương |

### 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)"
      }
    ]
  }
}

```

| | |
| :--- | :--- |
| Interoperability quốc tế | `http://loinc.org`(ưu tiên) |
| Trao đổi nội bộ VN / BHXH | `vn-cls-cs`(mã CLS VN) |
| Cả hai | Ghi 2 coding — LOINC trước, CLS sau |

**5 nhóm CLS:**

| | | |
| :--- | :--- | :--- |
| Huyết học — Truyền máu | 1000001–1001022 | 1.022 |
| Sinh hóa | 1010001–1010447 | 447 |
| Vi sinh | 1020001–1020174 | 174 |
| Giải phẫu bệnh | 1060001–1060081 | 81 |
| Chẩn đoán hình ảnh | 1070001–1071240 | 1.240 |

### 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.

| | | |
| :--- | :--- | :--- |
| `VNMedicalDeviceNomenclatureCS` | QĐ-3107/QĐ-BYT-2024 + QĐ-847/QĐ-BYT-2025 | 956 concept, display/definition tiếng Việt, tên tiếng Anh trong`designation`, định nghĩa tiếng Anh trong property`definitionEn` |
| `VNMedicalDeviceNomenclatureVS` | Include toàn bộ`VNMedicalDeviceNomenclatureCS` | Tập đầy đủ để tra cứu và kiểm tra coverage |
| `VNDeviceTypeVS` | Include toàn bộ`VNMedicalDeviceNomenclatureCS` | Dùng làm binding`preferred`cho`Device.type`/`DeviceDefinition.type`trong package`.device`, không dùng`required`trong Core |

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
1. Nếu không tìm thấy, sử dụng`coding`từ CodeSystem khác (ví dụ: SNOMED CT quốc tế)
1. 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

| | |
| :--- | :--- |
| Danh mục CodeSystem/ValueSet | [Terminology](terminology.md) |
| Hướng dẫn kiểm tra hợp lệ binding | [Validation Guidance](validation-guidance.md) |
| Cơ sở pháp lý các bộ mã | [Legal Basis](legal-basis.md) |
| Đính chính SNOMED CT VN | [SNOMED CT VN Errata](snomed-vn-errata.md) |

-------

## 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.

