HL7 Vietnam VN Core FHIR Implementation Guide

Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam
0.3.0 - STU1 Draft Viet Nam cờ

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

Mapping URI/OID

Ánh xạ URI/OID cho định danh và hệ mã lịch sử — Identifier and OID Mapping

Trang này mô tả cách VN Core xử lý quan hệ giữa:

  • System URI chuẩn trong FHIR
  • URN/OID legacy nếu có
  • Các field hoặc payload cũ trong XML/gateway/hệ thống nội bộ

Mục tiêu là giúp bên triển khai bắc cầu dữ liệu cũ sang FHIR mà không làm rối lớp định danh chuẩn.

Trang này dành cho ai?

  • Nhóm tích hợp đang chuyển đổi từ XML, OID, URI lịch sử hoặc hệ thống cũ sang FHIR.
  • Nhóm kiến trúc cần ban hành quy tắc canonical URI thống nhất.
  • Nhóm reviewer cần xác định đâu là ánh xạ tạm thời, đâu là định nghĩa chuẩn phải giữ lâu dài.

Dùng trang này khi nào?

  • Khi một hệ thống cũ chỉ biết OID, URN hoặc field định danh nội bộ.
  • Khi cần bắc cầu từ gateway/BHYT/XML sang system URI chuẩn của VN Core.
  • Khi có tranh luận về việc có nên tạo thêm OID mới hay không.

Kỷ luật canonical hiện tại

VN Core hiện tại cố ý siết chặt hơn ở 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ộ.

Nói ngắn gọn: điều được giữ lại là cần có registry định danh rõ; điều bị loại bỏ là mọi canonical hoặc OID thiếu kỷ luật.

1. Nguyên tắc chung

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

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

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

2. Á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

3. Á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õ

4. Mapping từ gateway/XML layer sang FHIR

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

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

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

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

English Summary

This page explains how VN Core bridges canonical FHIR URIs with legacy OID or URN usage. VN Core follows a URI-first policy for new FHIR artifacts and only uses OID as a legacy bridge when a code system or old integration environment genuinely depends on it. Implementers should map legacy XML or gateway fields into Identifier.system using VN Core URIs, rather than inventing new OIDs for local Vietnamese identifier systems.