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 chung

Hướng dẫn chung — General Guidance

Các quy tắc nền dưới đây áp dụng chung cho VN Core: cách biểu diễn tên, địa chỉ, định danh, pattern datatype và ranh giới giữa guidance chung với các trang chuyên đề.

Baseline quốc tế trước, Việt hoá sau

VN Core hiện tại đi theo nguyên tắc: dùng baseline quốc tế trước, rồi chỉ Việt hoá ở nơi thật sự cần.

• Với resource và datatype, ưu tiên FHIR R4, IPS và extension chuẩn của HL7 nếu đã diễn đạt đúng ngữ nghĩa.
• Chỉ localize khi Việt Nam có khác biệt thật về pháp lý, luồng công việc, định danh, địa chỉ hành chính hoặc bộ mã vận hành.
• Nếu một khác biệt chỉ là cách hiển thị, cách search hoặc cách ánh xạ gateway, nên giải quyết ở tài liệu hướng dẫn hoặc lớp triển khai trước khi tạo thêm profile/extension.

Pattern dùng lại xuyên suốt nhiều hồ sơ

Không để mỗi profile tự định nghĩa lại một pattern cho cùng một datatype. Các pattern dùng lại được giữ ở trang diễn giải và quản trị thay vì lặp lại trong từng profile:

Must Support (MS)

Chi tiết cách diễn giải và cẩm nang HIS -> FHIR đã được tách sang trang riêng: Hướng dẫn Must Support.

Đị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 xử lý được dữ liệu của element đó mà không gây lỗi (SHALL:no-error + SHALL:handle). Nghĩa vụ lưu trữ (SHALL:persist) chỉ áp cho actor giữ kho — Kho hồ sơ EMR; actor chỉ đọc như Citizen App và Data Requester không mang nghĩa vụ này (xem Tuân thủ theo vai trò)

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

Ví dụ — Must Support

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

Khi element MS không có giá trị, hệ thống cần phân biệt cardinality:

• Với element có cardinality tối thiểu lớn hơn 0, vẫn phải khai phần tử và dùng Data Absent Reason extension (http://hl7.org/fhir/StructureDefinition/data-absent-reason) khi profile cho phép.
• Với element tuỳ chọn (0..x), có thể bỏ phần tử; không tạo element rỗng chỉ để biểu thị thiếu dữ liệu.

Tên tiếng Việt trong FHIR

Cấu trúc HumanName

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

Quy tắc

1. text nên được điền khi nguồn có họ tên đầy đủ chính thức; VN Core đánh dấu name.text là 0..1 MS, không phải phần tử bắt buộc.
2. Ánh xạ family và given theo cấu trúc tên do nguồn có thẩm quyền cung cấp; không suy ra máy móc chỉ từ vị trí từ đầu tiên.
3. Giữ nguyên thứ tự các thành phần trong given; dùng text để bảo toàn cách viết chính thức.
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ờ

Ví dụ — Tên

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

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"

Địa chỉ Việt Nam

Cấu trúc VNCoreAddress

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

Địa chỉ chỉ có text

VNCoreAddress hỗ trợ chính thức địa chỉ chỉ có text, kể cả khi country = "VN". Không tạo mã giả, extension rỗng hoặc data-absent-reason chỉ để thay một mã tỉnh/xã chưa biết. province và ward là 0..1 MS: gửi mã đã xác minh khi nguồn có; bên nhận phải xử lý được khi mã được cung cấp. Bổ sung mã không làm mất hoặc tự thay đổi địa chỉ gốc. Tên xã/phường giữ trong text hoặc line; không dùng Address.city cho cấp xã.

Ví dụ: Patient có địa chỉ dạng chữ và Organization có địa chỉ dạng chữ.

Tương thích ngược

Giữ text, mã và ngày hồ sơ nguồn. Ba CodeSystem dùng chung canonical theo cấp cho mã đã thu nhận; history ValueSet không chứng minh hiệu lực tại một ngày. Danh sách chọn mới lấy từ vn-province-vs và vn-ward-vs tại mốc của bản dữ liệu. $lookup(date) chỉ trả tên/cha trong khoảng có bằng chứng; thiếu ngày hoặc thiếu khoảng trả không đủ căn cứ. Không tự dùng Address.period làm ngày hồ sơ.

Mã huyện nhà nước gồm ba chữ số. Với nguồn TMS hoặc mã ghép tỉnh+huyện năm chữ số, dùng registry chuyển biểu diễn với hệ mã và phiên bản tường minh; không cắt chuỗi để đoán mã. Danh mục content=fragment giữ 716 mã huyện quan sát được, không gán cùng ngày kết thúc cho mọi huyện. NQ 203/2025/QH15 Điều 2 khoản 2 quy định kết thúc hoạt động cấp huyện từ 01/07/2025; nghị quyết này không chứng minh từng huyện còn tồn tại ngay trước mốc đó. Xem hướng dẫn chuyển đổi.

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

Để tra cứu tập trung các NamingSystem, xem thêm Danh mục định danh. Để bắc cầu với OID hoặc hệ thống cũ, xem Ánh xạ URI/OID.

Thứ tự ưu tiên

CCCD: CCCD là định danh cá nhân lõi cho công dân Việt Nam trong VN Core.
VNeID: VNeID là tài khoản định danh điện tử và kênh truy cập của ứng dụng người dân; chỉ nên dùng ở lớp ứng dụng người dân, xác thực hoặc tích hợp, không dùng song song với CCCD như một định danh người bệnh chính.

Khi chưa có CCCD

CCCD là lát cắt định danh chính, nhưng không phải lát cắt bắt buộc: identifier[CCCD] là 0..1. Điều kiện phải thoả là invariant vn-patient-identifier-minimum — có ít nhất một định danh dùng được. Ba tình huống:

Hai lưu ý dễ làm sai:

• data-absent-reason trên CCCD không miễn được invariant. Nó nói "không có giá trị", không nói "vì sao được phép không có". Bơm một lát CCCD rỗng chỉ để giữ chỗ là thừa, và vì identifier[CCCD].value là 1..1 nên cách làm đó dễ sinh lỗi validate hơn là bỏ hẳn lát.
• Không dùng forceMajeureReason để mô tả người bệnh có định danh thay thế hợp lệ như hộ chiếu hoặc giấy khai sinh — đó là ca có định danh, không phải ca bất khả kháng.

Cấu trúc CCCD

Số CCCD 12 chữ số mã hoá thông tin:

• Vị trí 1-3: Mã prefix nơi đăng ký khai sinh theo danh mục 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

Mã prefix BCA này là terminology hỗ trợ validation cho CCCD đã cấp và không thay thế cho VNProvinceCS dùng trong địa chỉ hành chính hiện hành.

Chi tiết kiểm tra hợp lệ: xem Hướng dẫn kiểm tra hợp lệ

Tìm kiếm và so khớp định danh

• Với CCCD, BHYT, BHXH, GPHN, CCHN, MA_LK, MA_LUOT_KCB và mã phản hồi gateway BHYT, nên coi tìm kiếm là truy vấn nghiệp vụ chính xác theo kiểu token khi hệ thống công bố search tương ứng.
• Không nên biến tìm kiếm theo định danh thành tìm kiếm mờ theo văn bản tự do.
• Các hành vi normalize như bỏ khoảng trắng hoặc chuẩn hoá dấu gạch nối chỉ nên là hành vi nội bộ và cần công bố rõ nếu có.

Chi tiết xem Hành vi tìm kiếm.

Organization và Location

Không trộn 4 khái niệm khác nhau

Khi triển khai Organization và Location, VN Core tách riêng:

vn-ext-org-level chỉ biểu diễn cấp quản lý hành chính y tế hiện hành, không thay cho tuyến kỹ thuật cũ.

Khuyến nghị điền dữ liệu

• Bệnh viện/phòng khám: ưu tiên organizationType, organizationLevel, facilityCareLevel; chỉ điền organizationRank khi có căn cứ pháp lý rõ.
• Trạm y tế: thường không có hạng pháp lý, nên dùng organizationRankStatus = not-applicable nếu cần diễn đạt rõ.
• CDC/đơn vị dự phòng/kiểm nghiệm: dùng healthUnitRank, không dùng organizationRank.
• Location không mang hạng pháp lý; chỉ nên mang facilityCareLevel khi địa điểm được quản trị như một phân hệ chuyên môn riêng.

Chi tiết: xem Quản trị Organization và Location.

Mức độ ràng buộc (Binding Strength)

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

Quy ước URL

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

English Summary

VN Core defines shared rules for Vietnamese names, addresses, identifiers, organizations, locations and terminology bindings. Administrative codes use stable canonicals; names and parentage require evidence at the record date. Text-only addresses remain supported. Historical membership does not establish temporal validity. Must Support requirements are explained separately.