VN Core FHIR Implementation Guide — Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Hướng dẫn chung

Hướng dẫn chung — General Guidance

Trang này mô tả các quy tắc và hướng dẫn áp dụng chung khi triển khai VN Core FHIR IG.

1. Must Support (MS)

1.1. Định nghĩa

Trong VN Core IG, khi một element được đánh dấu Must Support (MS), nghĩa là:

• Hệ thống gửi (Sender): Nếu có dữ liệu cho element đó, PHẢI gửi kèm trong resource
• Hệ thống nhận (Receiver): PHẢI có khả năng xử lý và lưu trữ dữ liệu của element đó mà không gây lỗi

Must Support KHÔNG có nghĩa là element đó bắt buộc phải có giá trị (required). Một element có thể vừa MS vừa 0..1 — nghĩa là không bắt buộc có, nhưng nếu có thì phải hỗ trợ.

1.2. Ví dụ

1.3. Xử lý khi thiếu dữ liệu

Khi element MS không có giá trị, hệ thống nên:

• Sử dụng Data Absent Reason extension (http://hl7.org/fhir/StructureDefinition/data-absent-reason) nếu cần giải thích lý do thiếu
• Không tạo element rỗng (empty element) — bỏ qua hoàn toàn

2. Tên tiếng Việt trong FHIR

2.1. Cấu trúc HumanName

Tên tiếng Việt có cấu trúc: Họ + Tên đệm + Tên gọi. Mapping sang FHIR:

2.2. Quy tắc

1. text luôn bắt buộc — chứa họ tên đầy đủ theo thứ tự Việt Nam (Họ trước, Tên sau)
2. family = Họ (phần đầu tiên)
3. given = mảng chứa tên đệm và tên gọi, theo đúng thứ tự
4. Dấu tiếng Việt: PHẢI giữ nguyên dấu Unicode (UTF-8). Không bỏ dấu, không chuyển ASCII
5. use = official cho tên chính thức trên CCCD/giấy tờ

2.3. Ví dụ

{
  "name": [{
    "use": "official",
    "text": "Nguyễn Văn An",
    "family": "Nguyễn",
    "given": ["Văn", "An"]
  }]
}

2.4. Trường hợp đặc biệt

• Tên 2 chữ (không có đệm): given chỉ có 1 phần tử. Ví dụ: Bảo Đại → family: "Bảo", given: ["Đại"]
• Họ kép: family chứa toàn bộ họ kép. Ví dụ: "Tôn Thất" → family: "Tôn Thất"
• Người nước ngoài: Dùng tên theo hộ chiếu, use: "official"

3. Địa chỉ Việt Nam

3.1. Cấu trúc VNCoreAddress

Địa chỉ Việt Nam sau NQ 202/2025 có 2 cấp chính (tỉnh + xã), nhưng VN Core hỗ trợ backward-compatible:

3.2. Backward Compatibility

• Hệ thống CŨ (trước 01/7/2025) có thể vẫn gửi mã huyện theo danh mục 63 tỉnh
• Hệ thống NHẬN nên chấp nhận cả mã cũ và mới
• VNDistrictCS giữ lại mã huyện cũ với status = inactive để hỗ trợ legacy

4. Hệ thống định danh (Identifier)

4.1. Thứ tự ưu tiên

4.2. Format CCCD

Số CCCD 12 chữ số mã hóa thông tin:

• Vị trí 1-3: Mã tỉnh nơi đăng ký khai sinh (mã BCA)
• Vị trí 4: Giới tính + thế kỷ sinh (0=Nam/19xx, 1=Nữ/19xx, 2=Nam/20xx, 3=Nữ/20xx)
• Vị trí 5-6: 2 chữ số cuối năm sinh
• Vị trí 7-12: Số ngẫu nhiên

Chi tiết validation: xem Hướng dẫn Validation

5. Binding Strength

VN Core IG sử dụng các mức binding theo FHIR:

6. Quy ước URL

English Summary

This page defines VN Core IG's general rules: Must Support means senders must include data if available and receivers must process it without error; Vietnamese names map to family (surname) + given (middle + first name) with full Unicode diacritics; addresses use the new 2-tier model (province + commune) with backward compatibility for districts; CCCD (12-digit national ID) is the primary identifier; and binding strengths follow standard FHIR conventions with Vietnamese CodeSystems.