Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Local Development build (v0.4.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Registry định danh

Danh mục định danh — Identifier Registry

VN Core công bố 18 NamingSystem hiện hành. Mỗi hệ thống kèm system URI, cơ quan quản lý, trạng thái hiện hành/lịch sử và search parameter liên quan.

VN Core áp dụng nguyên tắc URI-first. OID hoặc URN chỉ nên dùng như cầu nối cho hệ thống cũ hoặc khi bộ mã/quy ước gốc đã có định danh lịch sử ổn định.

Trang này phục vụ nhóm tích hợp, HIS/EMR/FHIR server và QA khi cần chọn đúng system URI, phân biệt định danh quốc gia với định danh cục bộ, và rà lại trạng thái áp dụng của từng hệ định danh.

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.

Nguyên tắc registry

Trong kiến trúc hiện tại, NamingSystem được coi là hạ tầng của liên thông quốc gia, không chỉ là chi tiết của Patient hay Organization. Registry này tuân theo các nguyên tắc sau:

• Mỗi định danh có system URI chuẩn, vai trò rõ và phạm vi áp dụng rõ;
• Trạng thái hiện hành, lịch sử và ngừng dùng được tách nghĩa để tránh lẫn định danh công dân, định danh nghiệp vụ, payer identifier và định danh cục bộ;
• Registry định danh gắn trực tiếp với search, conformance, package governance và readiness triển khai.

---

Định danh quốc gia và liên tổ chức

Định danh	NamingSystem	URI chuẩn	Cơ quan quản lý	Trạng thái	Ghi chú triển khai
CCCD	vn-cccd-ns	http://fhir.hl7.org.vn/core/sid/cccd	Bộ Công an	Hiện hành	Định danh cá nhân chính; tìm kiếm: vn-sp-patient-cccd
CMND	vn-cmnd-ns	http://fhir.hl7.org.vn/core/sid/cmnd	Bộ Công an	Lịch sử / ngừng dùng	Chỉ dùng cho dữ liệu lịch sử hoặc chuyển đổi
BHXH	vn-bhxh-ns	http://fhir.hl7.org.vn/core/sid/bhxh	BHXH Việt Nam	Hiện hành	Tìm kiếm: vn-sp-patient-bhxh
BHYT	vn-bhyt-ns	http://fhir.hl7.org.vn/core/sid/bhyt	BHXH Việt Nam	Hiện hành	Hỗ trợ 3 format song song; tìm kiếm: vn-sp-patient-bhyt, vn-sp-coverage-bhyt
GKS	vn-gks-ns	http://fhir.hl7.org.vn/core/sid/gks	UBND cấp xã/phường/đặc khu	Hiện hành	Quan trọng cho trẻ em và luồng không dùng CCCD; tìm kiếm: vn-sp-patient-gks
Hộ chiếu	vn-passport-ns	http://fhir.hl7.org.vn/core/sid/passport	Bộ Công an / cơ quan cấp hộ chiếu hợp pháp	Hiện hành	Dùng cho người nước ngoài hoặc định danh thay thế hợp lệ
VNeID	vn-vneid-ns	http://fhir.hl7.org.vn/core/sid/vneid	Bộ Công an	Integration-only / retired	Chỉ giữ cho lớp tích hợp ứng dụng người dân; không dùng như định danh bệnh nhân lõi song song với CCCD
GPHN	vn-gphn-ns	http://fhir.hl7.org.vn/core/sid/gphn	Bộ Y tế / cơ quan cấp phép	Hiện hành	Tìm kiếm: vn-sp-practitioner-gphn
CCHN	vn-cchn-ns	http://fhir.hl7.org.vn/core/sid/cchn	Bộ Y tế	Lịch sử	Chỉ giữ cho liên thông hồ sơ cũ; tìm kiếm: vn-sp-practitioner-cchn
CSKCB	vn-ma-cskcb-ns	http://fhir.hl7.org.vn/core/sid/ma-cskcb	BHXH Việt Nam	Hiện hành	Tìm kiếm: vn-sp-organization-cskcb
MA_LK	vn-ma-lk-ns	http://fhir.hl7.org.vn/core/sid/ma-lk	Cơ sở KCB / lớp liên thông hồ sơ BHYT	Hiện hành	Tìm kiếm: vn-sp-claim-ma-lk
MA_LUOT_KCB	vn-ma-luot-kcb-ns	http://fhir.hl7.org.vn/core/sid/ma-luot-kcb	Cơ sở KCB	Hiện hành	Tìm kiếm: vn-sp-encounter-ma-luot-kcb

---

Định danh cục bộ theo cơ sở hoặc hệ thống

Định danh	NamingSystem	URI chuẩn	Phạm vi	Trạng thái	Ghi chú triển khai
MRN	vn-mrn-ns	http://fhir.hl7.org.vn/core/sid/mrn	Từng cơ sở y tế	Hiện hành	Không dùng như định danh gốc liên tổ chức
Mã tổ chức nội bộ	vn-organization-local-id-ns	http://fhir.hl7.org.vn/core/sid/organization-local-id	Từng tổ chức	Hiện hành	Không thay thế CSKCB
Mã địa điểm nội bộ	vn-location-local-id-ns	http://fhir.hl7.org.vn/core/sid/location-local-id	Từng tổ chức	Hiện hành	Dùng cho Location.identifier
Mã tài liệu nội bộ	vn-document-number-ns	http://fhir.hl7.org.vn/core/sid/document-number	Từng tổ chức	Hiện hành	Dùng cho Composition.identifier, DocumentReference.identifier
Mã specimen nội bộ	vn-specimen-local-id-ns	http://fhir.hl7.org.vn/core/sid/specimen-local-id	Từng tổ chức	Hiện hành	Dùng cho accession number của LIS/HIS
Mã vật tư y tế	vn-ma-vat-tu-ns	http://fhir.hl7.org.vn/core/sid/ma-vat-tu	Nghiệp vụ nội bộ / BHYT	Hiện hành	Dùng cho Device.identifier trong ngữ cảnh nghiệp vụ phù hợp

---

Định danh Device và khoa/phòng Wave 2

Các identifier dưới đây được dùng bởi các profile Wave 2. Một số là slice trên Identifier, một số là vị trí FHIR base hoặc CodeSystem dùng như Identifier.system.

Tên	System URI	Nguồn	Ghi chú
Mã VTYT (maVTYT)	http://fhir.hl7.org.vn/core/sid/ma-vat-tu	BHXH/BYT, dữ liệu đầu ra KCB	Định danh vật tư/thiết bị y tế trong XML đầu ra KCB; dùng cho slice maVTYT của VNCoreDevice.identifier
UDI Device Identifier (udiDI)	FHIR base Device.udiCarrier.deviceIdentifier; optional identifier slice http://fhir.hl7.org.vn/core/sid/udi-di	IMDRF/GS1/HIBCC	Best practice quốc tế; không phải căn cứ pháp lý bắt buộc của Việt Nam trong phiên bản hiện hành
Mã khoa K01-K53, K99	http://fhir.hl7.org.vn/core/CodeSystem/vn-department-cs	QĐ 2010/QĐ-BYT ngày 19/06/2025 Phụ lục 6	Dùng cho VNCoreOrganizationDepartment.identifier[departmentCode]

---

Cách dùng registry này

Khi nào dùng URI của VN Core

Dùng system URI của VN Core khi:

• Cần định danh rõ một loại identifier trong resource FHIR.
• Cần ánh xạ từ HIS/XML lịch sử sang FHIR.
• Cần xây chỉ mục tìm kiếm rõ ràng theo loại định danh.
• Cần phân biệt định danh hiện hành với định danh lịch sử.

Khi nào không nên dùng định danh cục bộ để liên thông rộng

Không nên dùng MRN, organization-local-id, location-local-id, specimen-local-id, hoặc document-number như định danh master liên tổ chức nếu chưa có thỏa thuận liên thông rõ.

Quy tắc chọn định danh ưu tiên

Ngữ cảnh	Ưu tiên khuyến nghị
Bệnh nhân công dân Việt Nam	CCCD
Bệnh nhân trẻ nhỏ / chưa có CCCD	GKS và/hoặc BHXH/BHYT
Bệnh nhân người nước ngoài	Hộ chiếu + citizenship phù hợp
Người hành nghề hiện hành	GPHN
Người hành nghề dữ liệu lịch sử	CCHN như cầu nối
Tổ chức KCB cho BHYT	CSKCB
Đợt gửi hồ sơ thanh toán BHYT	MA_LK
Lượt khám cụ thể	MA_LUOT_KCB

---

Ánh xạ URI và OID

Nguyên tắc canonical

VN Core áp dụng các nguyên tắc sau ở lớp canonical:

• Không phục dựng URI hoặc OID cũ nếu chúng không còn phù hợp với canonical discipline hiện tại;
• Không để một loại identifier mang nhiều ngữ nghĩa tùy bối cảnh;
• Không trộn canonical của định danh công dân, định danh payer, định danh tổ chức và định danh cục bộ.

Nguyên tắc chung

URI-first

VN Core ưu tiên URI làm định danh chuẩn cho:

• NamingSystem
• Identifier.system
• CodeSystem.url
• ValueSet.url

Điều này giúp:

• Nhất quán với FHIR tooling hiện nay
• Dễ triển khai hơn cho HIS vendor
• Tránh phải phát minh thêm OID không thật sự cần thiết

OID chỉ là cầu nối khi có lý do rõ ràng

OID hoặc urn:oid: chỉ nên được dùng khi:

• Bộ mã gốc quốc tế đã có OID ổn định
• Hệ thống legacy hoặc hồ sơ cũ đang dùng OID
• Cần bridge với tài liệu/bảng mã không thể đổi ngay

VN Core không đặt mục tiêu gán OID cho mọi định danh Việt Nam.

Không tự tạo OID chỉ để "giống JP Core"

JP Core có nhiều bối cảnh liên thông lịch sử đã dùng OID từ lâu. Việt Nam không nên sao chép máy móc mô hình đó.

Đối với phần lớn định danh Việt Nam như CCCD, BHYT, BHXH, GPHN, GKS, MA_LK, MA_LUOT_KCB, URI của VN Core là định danh chuẩn được ưu tiên.

Ánh xạ khuyến nghị cho định danh Việt Nam

Miền	Chuẩn VN Core nên dùng	OID/URN legacy	Khuyến nghị
CCCD	http://fhir.hl7.org.vn/core/sid/cccd	Không công bố OID trong VN Core	Dùng URI của VN Core
CMND	http://fhir.hl7.org.vn/core/sid/cmnd	Không công bố OID trong VN Core	Chỉ dùng cho cầu nối dữ liệu lịch sử
BHXH	http://fhir.hl7.org.vn/core/sid/bhxh	Không công bố OID trong VN Core	Dùng URI của VN Core
BHYT	http://fhir.hl7.org.vn/core/sid/bhyt	Không công bố OID trong VN Core	Dùng URI của VN Core
GKS	http://fhir.hl7.org.vn/core/sid/gks	Không công bố OID trong VN Core	Dùng URI của VN Core
Hộ chiếu	http://fhir.hl7.org.vn/core/sid/passport	Không công bố OID trong VN Core	Dùng URI của VN Core
GPHN	http://fhir.hl7.org.vn/core/sid/gphn	Không công bố OID trong VN Core	Dùng URI của VN Core
CCHN	http://fhir.hl7.org.vn/core/sid/cchn	Không công bố OID trong VN Core	Chỉ dùng cho dữ liệu lịch sử
CSKCB	http://fhir.hl7.org.vn/core/sid/ma-cskcb	Không công bố OID trong VN Core	Dùng URI của VN Core
MA_LK	http://fhir.hl7.org.vn/core/sid/ma-lk	Không công bố OID trong VN Core	Dùng URI của VN Core
MA_LUOT_KCB	http://fhir.hl7.org.vn/core/sid/ma-luot-kcb	Không công bố OID trong VN Core	Dùng URI của VN Core

Ánh xạ khuyến nghị cho bộ mã quốc tế hoặc lịch sử

Miền	Canonical khuyến nghị	OID legacy hay gặp	Ghi chú
ICD-10	http://hl7.org/fhir/sid/icd-10 hoặc CodeSystem chính thức đang dùng trong VN Core	2.16.840.1.113883.6.3	OID tồn tại hợp lệ, nhưng URI/canonical vẫn là lớp chính trong FHIR
LOINC	http://loinc.org	2.16.840.1.113883.6.1	Ưu tiên URI
SNOMED CT	http://snomed.info/sct	2.16.840.1.113883.6.96	Ưu tiên URI
ISO 3166 country code	official FHIR/THO canonical	tùy bối cảnh legacy	Không nên tự tạo local OID mapping nếu không có lý do rõ

Mapping từ gateway/XML layer sang FHIR

Với field định danh trong XML hoặc payload cũ

Khuyến nghị:

• Giữ nguyên value nếu giá trị gốc còn hợp lệ
• Map sang Identifier.system bằng URI của NamingSystem tương ứng
• Chỉ thêm alias OID/URN ở integration adapter nếu hệ thống ngoài FHIR vẫn cần

Ví dụ:

Field legacy	FHIR target
SO_CCCD	Identifier.system = http://fhir.hl7.org.vn/core/sid/cccd
MA_LK	Identifier.system = http://fhir.hl7.org.vn/core/sid/ma-lk
MA_LUOT_KCB	Identifier.system = http://fhir.hl7.org.vn/core/sid/ma-luot-kcb
số thẻ BHYT	Identifier.system = http://fhir.hl7.org.vn/core/sid/bhyt

Với bộ mã có OID gốc

Nếu hệ thống cũ lưu OID cho ICD-10/LOINC/SNOMED CT:

• Adapter MAY chuyển đổi về canonical URI trước khi xuất FHIR
• Resource FHIR nên dùng canonical URI/coding system chuẩn
• OID chỉ nên giữ ở lớp mapping hoặc audit log nếu cần traceability

Những gì không nên làm

• Không tạo OID nội bộ mới cho mọi bộ mã hoặc định danh Việt Nam.
• Không để cùng một loại định danh xuất hiện lúc thì dùng URI, lúc thì dùng OID, mà không có policy mapping rõ.
• Không coi OID là lớp định danh chính trong artifact FHIR mới.

---

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

Nếu cần	Nên đọc tiếp
Hiểu hành vi tìm kiếm theo token cho các identifier	Hành vi tìm kiếm
Xem quy tắc định danh và luồng không dùng CCCD	Hướng dẫn chung
Nắm quy tắc gói phát hành và mức độ tuân thủ	Ổn định và tuân thủ

---

English Summary

This page is the published identifier registry for VN Core NamingSystems. It shows which identifier URI should be used, who governs it, whether it is current, historical, or retired, and how each system relates to search and interoperability. VN Core follows a URI-first approach and keeps OID or URN aliases only as historical bridges when needed. The final section explains how to map legacy OID/URN identifiers and gateway/XML fields to canonical FHIR URIs.