VN Core Deep Dive

Cách đọc một Profile trong VN Core

Profile là nơi VN Core biến FHIR base thành hợp đồng dữ liệu cho Việt Nam. Đọc đúng profile giúp bạn biết element nào bắt buộc, element nào Must Support, mã nào được dùng, extension nào cần đọc và example nào chứng minh payload hợp lệ.

Tóm tắt nhanh

  • Đọc differential trước snapshot. Differential cho thấy phần VN Core thêm vào; snapshot chủ yếu phục vụ validator.
  • Must Support không phải required. Required là cardinality `min > 0`; Must Support là nghĩa vụ hệ thống trong scope của IG.
  • Slicing là nơi định danh Việt Nam xuất hiện rõ nhất. Patient.identifier có thể có CCCD, BHYT, BHXH, MRN, giấy khai sinh với system khác nhau.
  • Binding phải đọc cùng ValueSet. `Coding.display` chỉ để hiển thị, còn `system + code + version` mới quyết định nghĩa máy đọc.

1. Tám tín hiệu cần đọc trên mọi Profile

Canonical URL

Định danh ổn định của profile. Payload khai báo trong `meta.profile`; validator dùng URL này để chọn constraint.

Differential

Phần VN Core thật sự thêm hoặc siết so với base/profile cha. Đây là nơi nên đọc đầu tiên.

Snapshot

Toàn bộ cấu trúc sau khi merge base + differential. Cần cho validator, nhưng quá dài để đọc đầu tiên.

Cardinality

Số lần element được phép xuất hiện. `1..1` nghĩa là bắt buộc đúng một lần; `0..*` nghĩa là tùy chọn lặp.

Must Support

Client/server thuộc scope của IG phải hiểu và xử lý element này; không đồng nghĩa element luôn bắt buộc xuất hiện.

Slicing

Chia một mảng như `identifier[]` thành các lát có ý nghĩa riêng: CCCD, BHYT, BHXH, MRN.

Binding

Ràng buộc element coded vào ValueSet. Binding mới quyết định mã nào hợp lệ, không phải `display`.

Example

Cách tốt nhất để hiểu profile trong workflow thật và tránh hiểu sai reference/slice.

2. Must Support và cardinality khác nhau thế nào

Cardinality trả lời câu hỏi instance có phải chứa element hay không. Nếu một element có cardinality 1..1, payload thiếu element đó sẽ không validate. Nếu là 0..1, payload có thể thiếu element mà vẫn hợp lệ.

Must Support trả lời câu hỏi hệ thống trong phạm vi IG có phải hiểu và xử lý element hay không. Một element 0..1 MS vẫn có thể vắng mặt trong từng payload, nhưng server/client tuân thủ VN Core không được bỏ qua khi element xuất hiện. Với Patient, CCCD có thể là slice required trong profile nền, còn BHYT hoặc BHXH có thể Must Support để phục vụ workflow bảo hiểm và liên thông.

Quy tắc review: khi đọc một profile, đừng chỉ scan `1..1`. Hãy đọc cả cột Must Support và phần mô tả capability. Nhiều lỗi tích hợp xảy ra vì nhà cung cấp pass validator nhưng không xử lý element Must Support mà workflow Việt Nam cần.

3. Slicing identifier: ví dụ Patient Việt Nam

FHIR base chỉ nói Patient.identifier là mảng identifier. VN Core cần phân biệt từng loại định danh vì mỗi loại có cơ quan quản lý, format và workflow khác nhau. Slicing cho phép cùng một mảng có nhiều lát có tên riêng:

Patient.identifier
  ├── identifier[CCCD]  system = .../sid/cccd   value = 12 digits
  ├── identifier[BHYT]  system = .../sid/bhyt   value = mã thẻ BHYT
  ├── identifier[BHXH]  system = .../sid/bhxh   value = 10 digits
  ├── identifier[MRN]   system = hospital MRN   value = mã bệnh nhân nội bộ
  └── identifier[GKS]   system = giấy khai sinh value = số giấy khai sinh

Khi bộ chuyển đổi HIS gửi Patient, validator không chỉ kiểm tra identifier có tồn tại. Nó còn kiểm tra slice nào match discriminator, system có đúng URI không, value có đúng pattern không, và cardinality của từng slice có thỏa không.

4. Binding và terminology

Element dạng coded như Condition.code, Observation.code, Patient.gender hoặc extension dân tộc không tự do nhập text. Profile bind element đó vào một ValueSet với strength cụ thể. Nếu strength là required, code phải nằm trong expansion của ValueSet; nếu là extensible, nên dùng code trong ValueSet khi có code phù hợp, chỉ dùng mã ngoài khi thật sự không có.

Với dữ liệu Việt Nam, đọc binding đặc biệt quan trọng vì cùng một label hiển thị có thể xuất hiện trong nhiều hệ thống mã. "Kinh" trong dân tộc, "A00" trong ICD-10, "DN" trong mã thẻ BHYT hoặc "01" trong nhiều danh mục khác nhau chỉ có nghĩa rõ khi đi cùng system. Đây là lý do VN Core duy trì CodeSystem và ValueSet riêng cho từng domain.

5. Checklist trước khi claim "tuân thủ VN Core"

Payload khai báo đúng `meta.profile` cho profile cần validate.
Các identifier dùng đúng `system` URI, không chỉ đúng format value.
Element required có mặt; element Must Support được hệ thống xử lý khi xuất hiện.
CodeableConcept dùng đúng `system + code`, không dựa vào `display`.
Extension có URL canonical đúng và value[x] đúng kiểu dữ liệu profile khai báo.
Reference trỏ tới resource/profile đúng scope, không chỉ là string ID tùy ý.
Example pass validator với package VN Core cùng version release.