# Registry định danh - Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam v0.5.0

## Registry định danh

# Danh mục định danh — Identifier Registry

VN Core `v0.5.0` công bố 22 `NamingSystem`. 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

| | | | | | |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 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` |
| Cổng`gdbhyt` | `vn-gdbhyt-portal-ns` | `https://gdbhyt.baohiemxahoi.gov.vn` | BHXH Việt Nam | Hiện hành trong v0.5 | Dùng cho[VNCoreEndpointBHYT](StructureDefinition-vn-core-endpoint-bhyt.md)và`Organization.endpoint`; không dùng như identifier hồ sơ |
| `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` |
| `XML1_ID`/ mã phản hồi gateway BHYT | `vn-bhyt-gateway-response-id-ns` | `http://fhir.hl7.org.vn/core/sid/bhyt-gateway-response-id` | Cổng tiếp nhận dữ liệu BHYT | Hiện hành trong lớp BHYT Submission | Dùng cho`ClaimResponse.identifier[gatewayResponseId]`; không thay thế`MA_LK`; tìm kiếm:`vn-sp-claim-response-xml1-id` |
| `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

| | | | | | |
| :--- | :--- | :--- | :--- | :--- | :--- |
| 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 |
| Số accession CĐHA | `vn-imaging-accession-number-ns` | `http://fhir.hl7.org.vn/core/sid/imaging-accession-number` | Từng RIS/PACS/HIS | Hiện hành từ v0.4 | Dùng cho`ImagingStudy.identifier`để đối soát chỉ định, thực hiện và lưu trữ hình ảnh |
| Mã vật tư/thiết bị y tế | `vn-medical-device-item-code-ns` | `http://fhir.hl7.org.vn/core/sid/medical-device-item-code` | Nghiệp vụ nội bộ / BHYT | Hiện hành | Dùng cho`Device.identifier[medicalDeviceItemCode]`trong ngữ cảnh legacy/BHYT; dòng chi phí ưu tiên`Claim.item.productOrService` |
| Số lưu hành thiết bị y tế | `vn-medical-device-registration-number-ns` | `http://fhir.hl7.org.vn/core/sid/medical-device-registration-number` | Bộ Y tế / Cục Hạ tầng và Thiết bị y tế | Hiện hành từ v0.5 | Định danh regulatory ở mức sản phẩm/model; không thay UDI, serial number hoặc`MA_VAT_TU` |

-------

## Định danh Device, CĐHA, khoa/phòng và gateway v0.4-v0.5

Các identifier dưới đây được dùng bởi các profile bổ sung từ `v0.4` đến `v0.5.0`. Một số là slice trên `Identifier`, một số là vị trí FHIR base, endpoint URL hoặc CodeSystem dùng như `Identifier.system`.

| | | | |
| :--- | :--- | :--- | :--- |
| Mã VTYT/TBYT (`MA_VAT_TU`) | `http://fhir.hl7.org.vn/core/sid/medical-device-item-code` | BHXH/BYT, dữ liệu đầu ra KCB | Mã vật tư/thiết bị y tế trong XML đầu ra KCB; dùng cho slice`medicalDeviceItemCode`của[VNCoreDevice.identifier](StructureDefinition-vn-core-device.md)khi cần trace legacy, không dùng thay UDI |
| Số lưu hành TBYT | `http://fhir.hl7.org.vn/core/sid/medical-device-registration-number` | NĐ 98/2021/NĐ-CP, NĐ 07/2023/NĐ-CP, NĐ 04/2025/NĐ-CP và cơ quan quản lý thiết bị y tế | Bổ sung trong`v0.5.0`cho[VNCoreExtDeviceRegistrationNumber](StructureDefinition-vn-ext-device-registration-number.md); định danh regulatory ở mức sản phẩm/model, không phải instance identifier |
| UDI Device Identifier | FHIR base`Device.udiCarrier.deviceIdentifier`; search bằng core parameter`udi-di` | IMDRF/GS1/HIBCC | Best practice quốc tế; không tạo local NamingSystem khi FHIR base đã có vị trí chuẩn |
| Mã danh pháp thiết bị y tế | Không phải`Identifier.system`trong Core;`VNMedicalDeviceNomenclatureCS`thuộc package`.device`theo ADR-0011 | QĐ 3107/QĐ-BYT, QĐ 847/QĐ-BYT | Dùng cho`Device.type`/`DeviceDefinition.type`trong package`.device`với binding`preferred`; không dùng thay UDI,`MA_VAT_TU`, số lưu hành hoặc mã tài sản |
| Số accession CĐHA | `http://fhir.hl7.org.vn/core/sid/imaging-accession-number` | Cơ sở vận hành RIS/PACS/HIS | Dùng cho[VNCoreImagingStudy.identifier](StructureDefinition-vn-core-imaging-study.md)để nối chỉ định, kết quả, hình ảnh và lưu trữ PACS |
| 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]](StructureDefinition-vn-core-organization-department.md) |
| Endpoint cổng`gdbhyt` | `https://gdbhyt.baohiemxahoi.gov.vn` | NĐ 164/2025/NĐ-CP và quy định giao dịch điện tử BHXH/BHYT | Bổ sung trong`v0.5.0`cho[VNCoreEndpointBHYT](StructureDefinition-vn-core-endpoint-bhyt.md); đây là endpoint/gateway address, không phải mã hồ sơ |

-------

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

| | |
| :--- | :--- |
| 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 |
| Endpoint cổng gửi/tra cứu BHYT | `gdbhyt`portal URI trên`Endpoint.address` |
| Đợt gửi hồ sơ thanh toán BHYT | `MA_LK` |
| Lượt khám cụ thể | `MA_LUOT_KCB` |
| Thiết bị y tế loại B/C/D theo regulatory context | Số lưu hành thiết bị y tế |

-------

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

| | | | |
| :--- | :--- | :--- | :--- |
| 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 |
| Cổng`gdbhyt` | `https://gdbhyt.baohiemxahoi.gov.vn` | Không công bố OID trong VN Core | Dùng URL endpoint chính thức cho`Endpoint.address` |
| `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 |
| `XML1_ID`/ mã phản hồi gateway BHYT | `http://fhir.hl7.org.vn/core/sid/bhyt-gateway-response-id` | Không công bố OID trong VN Core | Chỉ dùng cho phản hồi tiếp nhận/giám định; không thay`MA_LK` |
| `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 |
| Số accession CĐHA | `http://fhir.hl7.org.vn/core/sid/imaging-accession-number` | Không công bố OID trong VN Core | Dùng cho accession number theo cơ sở/hệ RIS/PACS |
| Số lưu hành TBYT | `http://fhir.hl7.org.vn/core/sid/medical-device-registration-number` | Không công bố OID trong VN Core | Dùng cho regulatory identifier ở mức sản phẩm/model |

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

| | | | |
| :--- | :--- | :--- | :--- |
| 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ụ:

| | |
| :--- | :--- |
| `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` |
| `XML1_ID` | `ClaimResponse.identifier.system = http://fhir.hl7.org.vn/core/sid/bhyt-gateway-response-id` |
| `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` |
| số accession CĐHA | `ImagingStudy.identifier.system = http://fhir.hl7.org.vn/core/sid/imaging-accession-number` |
| số lưu hành TBYT | `Device.identifier.system = http://fhir.hl7.org.vn/core/sid/medical-device-registration-number` |
| cổng gửi BHYT | `Endpoint.address = https://gdbhyt.baohiemxahoi.gov.vn` |

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

| | |
| :--- | :--- |
| Hiểu hành vi tìm kiếm theo token cho các identifier | [Hành vi tìm kiếm](search-behavior.md) |
| Xem quy tắc định danh và luồng không dùng CCCD | [Hướng dẫn chung](general-guidance.md) |
| Nắm quy tắc gói phát hành và mức độ tuân thủ | [Ổn định và tuân thủ](stability-and-conformance.md) |

-------

## English Summary

This page is the published identifier registry for VN Core v0.5.0 NamingSystems. It shows which identifier URI to use, who governs it, and how it relates to search and interoperability. The v0.5 update adds BHYT gateway endpoint, imaging accession, and medical device registration identifiers. VN Core remains URI-first; OID/URN aliases are only historical bridges.

