Profile, Extension, Implementation Guide: cách FHIR được bản địa hóa

1. Vì sao FHIR base không đủ cho y tế Việt Nam

Resource cơ sở của FHIR R4 (4.0.1, 146 resources) được thiết kế ở mức tổng quát toàn cầu. Tài nguyên Patient chuẩn cho phép identifier[] với cardinality 0..*, không yêu cầu định danh cụ thể nào. Nó có address với các thành phần line, city, district, state, postalCode, country, nhưng không có trường mã hóa xã/phường — đơn vị hành chính cơ sở trong mô hình chính quyền địa phương hai cấp sau Nghị quyết 202/2025/QH15.

Nghiệp vụ y tế Việt Nam đặt ra một loạt yêu cầu cụ thể mà FHIR base không đáp ứng trực tiếp. Thông tư 13/2025/TT-BYT áp dụng lộ trình bệnh án điện tử cho bệnh viện và các cơ sở khám bệnh, chữa bệnh khác có điều trị nội trú, điều trị ban ngày hoặc điều trị ngoại trú; Điều 1 khoản 3 yêu cầu kết nối thông tin bệnh án điện tử với số định danh cá nhân của công dân Việt Nam và của người nước ngoài đã được cấp tài khoản định danh điện tử. Văn bản không tạo hai lựa chọn giữa số định danh và tài khoản VNeID, cũng không tự quy định một slice CCCD 12 chữ số bắt buộc trong FHIR: định dạng 12 chữ số có căn cứ từ pháp luật về căn cước, còn cardinality của slice CCCD là quyết định conformance trial-use của VN Core. Thanh toán BHYT yêu cầu các trường như mã số BHYT, nhóm đối tượng, nơi đăng ký khám chữa bệnh ban đầu và thời hạn theo bộ dữ liệu áp dụng. Các bộ dữ liệu y tế/KCB/BHYT còn sử dụng dân tộc, nghề nghiệp, hạng cơ sở, cấp chuyên môn kỹ thuật và mã đơn vị hành chính theo từng nguồn quy định.

Profile và Extension giải bài toán bản địa hóa bằng cách bổ sung ràng buộc và trường dữ liệu trên cấu trúc FHIR R4. Một instance tuân thủ VNCorePatient vẫn phải hợp lệ theo Patient base, nhưng quan hệ kế thừa này không bảo đảm mọi server hoặc client R4 hiểu, kiểm tra hay bảo toàn các extension và semantics của VN Core. Muốn tuyên bố tương tác, hai bên phải dùng đúng package và phiên bản IG, công bố capability trong CapabilityStatement, rồi kiểm thử validation, round-trip và workflow trên contract đã thống nhất.

2. Profile là gì — pattern ràng buộc

Một Profile là một StructureDefinition derive (kế thừa) từ Resource cơ sở hoặc từ một Profile khác, thêm ràng buộc bổ sung. Profile không tự định nghĩa cấu trúc dữ liệu mới, nó chỉ siết tập hợp giá trị hợp lệ mà instance phải tuân theo. Sơ đồ kế thừa của VNCorePatient minh họa rõ:

Patient (base — http://hl7.org/fhir/StructureDefinition/Patient)
   └── derive
       VNCorePatient (http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-patient)
       - identifier slices: CCCD 1..1 MS; BHYT/BHXH/GKS/HC 0..1 MS; MRN 0..* MS
       - Patient extensions: ethnicity, occupation, citizenship, religion, birthPlace
       - address 0..* MS, constrained to VNCoreAddress
       - VNCoreAddress: province and ward extensions 0..1 MS;
         a Vietnamese address is expected to carry a coded province

Bốn quy tắc bất di bất dịch của Profile

Khi viết Profile, có bốn quy tắc về tính tương thích bắt buộc phải tôn trọng. Vi phạm bất kỳ quy tắc nào sẽ làm Profile không còn là constraint hợp lệ trên base, dẫn tới instance không thể đọc bằng client FHIR chuẩn:

1. Không được nới lỏng cardinality: nếu base định nghĩa 1..1, Profile không thể đổi sang 0..1; nếu base là 1..*, Profile không thể đổi sang 0..*.
2. Không được thay đổi data type: trường khai báo string trong base không thể đổi sang integer trong Profile; chỉ được giới hạn trong các kiểu base đã cho phép qua choice type.
3. Có thể siết cardinality: 0..1 có thể đổi thành 1..1; 0..* có thể đổi thành 1..* hoặc 1..3.
4. Có thể tăng độ chặt của binding: từ example sang preferred, extensible, hoặc required; nhưng không được hạ độ chặt của một binding đã required trên base.

Bốn quy tắc này đảm bảo nguyên tắc Liskov: mọi instance hợp lệ với Profile cũng hợp lệ với base, nhưng không nhất thiết ngược lại. Đây là lý do FHIR validator có thể kiểm tra một Patient instance vừa với spec base vừa với VNCorePatient mà không xảy ra mâu thuẫn.

3. Bốn loại constraint phổ biến

Cardinality

Cardinality định nghĩa số lần một element xuất hiện. Ký pháp FHIR dùng cặp min..max: 0..1 là tùy chọn đơn lẻ, 1..1 là bắt buộc đơn lẻ, 0..* là tùy chọn lặp, 1..* là bắt buộc lặp ít nhất một lần. VNCorePatient siết identifier 1..* để buộc mọi bệnh nhân phải có ít nhất một định danh, sau đó dùng slicing để chỉ định slice CCCD ở mức 1..1.

Binding strength

Binding gắn một element code, Coding hoặc CodeableConcept với một ValueSet. FHIR R4 định nghĩa bốn mức:

• required — instance bắt buộc dùng code thuộc ValueSet, validator báo lỗi nếu vi phạm.
• extensible — ưu tiên ValueSet, chỉ được dùng code ngoài nếu không có code phù hợp trong ValueSet.
• preferred — khuyến nghị nhưng không bắt buộc.
• example — minh họa, không ràng buộc gì.

Profile VNCoreCondition bind Condition.code với ValueSet ICD-10 VN ở mức extensible để cho phép sử dụng SNOMED CT khi mã ICD-10 không đủ chi tiết, đồng thời giữ ICD-10 VN làm danh mục ưu tiên.

Must Support

Must Support (đánh dấu MS) yêu cầu hệ thống tuân thủ Profile phải hỗ trợ element theo cách mà IG quy định. Spec FHIR cố ý không định nghĩa "support" cụ thể là gì ở mức toàn cầu — IG phải tự nêu rõ. VN Core quy ước rằng MS có nghĩa: server lưu trữ phải có khả năng ghi/đọc round-trip element này; client gửi dữ liệu phải gửi nếu có; UI hiển thị phải render element nếu được yêu cầu.

Must Support không phải là cardinality. Một element 0..1 MS vẫn có thể vắng mặt trong instance — nhưng hệ thống phải có khả năng xử lý khi nó xuất hiện. Cardinality 1..1 yêu cầu element hiện diện; với primitive, element có thể mang extension data-absent-reason mà không có giá trị primitive khi profile cho phép. VNCorePatient dùng pattern này cho slice CCCD trong các trường hợp đặc biệt và yêu cầu định danh thay thế hoặc lý do phù hợp.

Slicing

Slicing chia một array thành các "lát" được nhận diện qua discriminator. Từ VN Core v0.9.0, VNCorePatient phân loại identifier bằng pattern trên Identifier.type, không dùng Identifier.system làm discriminator. Cách này giữ URI hệ thống quốc gia cố định cho CCCD/BHYT/BHXH nhưng cho phép MRN dùng namespace riêng của từng cơ sở:

* identifier ^slicing.discriminator.type = #pattern
* identifier ^slicing.discriminator.path = "type"
* identifier ^slicing.rules = #open
* identifier contains
    CCCD 1..1 MS and
    BHYT 0..1 MS and
    BHXH 0..1 MS and
    MRN 0..* MS and
    HC 0..1 MS and
    GKS 0..1 MS
* identifier[CCCD].type = $vn-identifier-type-cs#CCCD
* identifier[BHYT].type = $vn-identifier-type-cs#BHYT
* identifier[BHXH].type = $vn-identifier-type-cs#BHXH
* identifier[MRN].type = $vn-identifier-type-cs#MRN
* identifier[HC].type = $vn-identifier-type-cs#HC
* identifier[GKS].type = $vn-identifier-type-cs#GKS
* identifier[CCCD].system = "http://fhir.hl7.org.vn/core/sid/cccd" (exactly)
* identifier[BHYT].system = "http://fhir.hl7.org.vn/core/sid/bhyt" (exactly)

Discriminator type = #pattern kết hợp path = "type" yêu cầu validator phân biệt slice theo pattern của identifier.type. Rule #open vẫn cho phép các identifier ngoài danh sách đã khai báo. MRN thuộc slice MRN, nhưng identifier[MRN].system phải là URI namespace do từng cơ sở công bố; tính duy nhất được xác định bằng cặp system + value.

4. Extension — khi nào và viết thế nào

Extension là cơ chế chuẩn để thêm trường dữ liệu mà FHIR base không có. Mọi Resource và DataType đều có sẵn trường extension với cardinality 0..*; mỗi extension được nhận diện qua một URL canonical duy nhất. Khi nghiệp vụ Việt Nam cần lưu loại đối tượng tham gia BHYT trên thẻ BHYT, VN Core định nghĩa VNCoreExtBHYTCardType:

Extension: VNCoreExtBHYTCardType
Id: vn-ext-bhyt-card-type
Title: "Loại đối tượng thẻ BHYT — BHYT Card Type"
Description: "Mã loại đối tượng tham gia BHYT theo QĐ 1351/QĐ-BHXH và QĐ 3276/QĐ-BYT"
Context: Coverage
* value[x] only CodeableConcept
* valueCodeableConcept from VNBHYTCardTypeVS (extensible)

URL canonical đầy đủ là http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-bhyt-card-type. Khi instance Coverage tham chiếu extension này, JSON serialize ra:

{
  "resourceType": "Coverage",
  "id": "example-coverage-bhyt-01",
  "status": "active",
  "extension": [{
    "url": "http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-bhyt-card-type",
    "valueCodeableConcept": {
      "coding": [{
        "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-bhyt-card-type-cs",
        "code": "DN",
        "display": "Người lao động doanh nghiệp"
      }]
    }
  }]
}

Extension chia thành hai loại. Simple extension chỉ chứa một value[x]. Complex extension chứa nhiều sub-extension lồng nhau. VN Core hiện xuất bản 56 extension, gồm 53 extension nội địa và 3 official HL7 Patient extension được tái sử dụng. Nhóm nội địa bao gồm VNCoreExtEthnicity (dân tộc), VNCoreExtWard (xã/phường), VNCoreExtProvince (tỉnh/thành), VNCoreExtFacilityCareLevel (tuyến chuyên môn kỹ thuật), VNCoreExtOrgRank (hạng cơ sở), VNCoreExtTreatmentOutcome (kết quả điều trị) và các extension khác phục vụ Claim, Coverage, Device, Encounter.

Nguyên tắc thiết kế: chỉ tạo extension khi đã chắc chắn FHIR base và các IG quốc tế đã publish (US Core, IPS, IPA) không có. Nếu một concept đã có extension chuẩn của HL7 (ví dụ patient-birthPlace, patient-citizenship), VN Core dùng lại thay vì tạo mới.

5. FSH và SUSHI — bộ công cụ chuẩn

FSH (FHIR Shorthand) là DSL được HL7 chuẩn hóa để viết Profile, Extension, ValueSet, CodeSystem dưới dạng văn bản gọn. SUSHI (SUSHI Unshortens SHorthand Inputs) là compiler chính thức biên dịch FSH ra StructureDefinition JSON. Bộ đôi FSH + SUSHI thay thế việc viết tay XML/JSON dài hàng nghìn dòng — cùng một profile có thể giảm từ 800 dòng JSON xuống còn 60 dòng FSH có cấu trúc dễ đọc.

Đây là profile VNCorePatient viết bằng FSH (rút gọn để minh họa):

Profile: VNCorePatient
Parent: Patient
Id: vn-core-patient
Title: "Bệnh nhân VN Core — VN Core Patient Profile"
Description: "Profile Patient cho Việt Nam. Slice số định danh cá nhân/CCCD
là quy tắc conformance trial-use của VN Core. Điều 1 khoản 3 TT 13/2025/TT-BYT
yêu cầu kết nối thông tin bệnh án với số định danh cá nhân của các nhóm
đối tượng được quy định; Thông tư không đặt tài khoản VNeID làm identifier thay thế."

* identifier 1..* MS
* identifier ^slicing.discriminator.type = #pattern
* identifier ^slicing.discriminator.path = "type"
* identifier ^slicing.rules = #open
* identifier contains
    CCCD 1..1 MS and
    BHYT 0..1 MS and
    MRN 0..* MS

* identifier[CCCD].type = $vn-identifier-type-cs#CCCD
* identifier[CCCD].system = "http://fhir.hl7.org.vn/core/sid/cccd" (exactly)
* identifier[CCCD].value 1..1 MS
* identifier[CCCD] obeys vn-cccd-format
* identifier[BHYT].type = $vn-identifier-type-cs#BHYT
* identifier[MRN].type = $vn-identifier-type-cs#MRN

* name 1..* MS
* gender 1..1 MS
* birthDate 1..1 MS
* address only VNCoreAddress

* extension contains
    VNCoreExtEthnicity named ethnicity 0..1 and
    VNCoreExtOccupation named occupation 0..1

* obeys vn-patient-force-majeure-reason

Lệnh sushi . chạy trong thư mục dự án sẽ đọc tất cả file .fsh, kiểm tra cú pháp, resolve các tham chiếu giữa Profile-Extension-ValueSet, và xuất ra fsh-generated/resources/StructureDefinition-vn-core-patient.json. Quy trình build IG đầy đủ tiếp tục bằng IG Publisher (file publisher.jar chính thức của HL7) để sinh HTML site, validation report, và package .tgz.

IG có thể được author bằng FSH hoặc trực tiếp bằng các artifact FHIR; lựa chọn phụ thuộc toolchain và governance của dự án. FSH thường giúp diff và review dễ đọc hơn, còn SUSHI kiểm tra và tạo artifact từ nguồn FSH. Tuy nhiên dependency package, canonical version và tính tương thích vẫn phải được khai báo, khóa phiên bản và kiểm thử; SUSHI không tự giải quyết mọi dependency về ngữ nghĩa.

6. Implementation Guide — cấu trúc và quy trình build

Implementation Guide là gói phát hành đầy đủ kết hợp specification và documentation. Một IG hoàn chỉnh chứa các thành phần sau:

• Profiles — StructureDefinition cho mỗi Resource được bản địa hóa.
• Extensions — StructureDefinition cho các trường thêm.
• Terminology — CodeSystem (định nghĩa code), ValueSet (tập hợp code dùng được trong binding), ConceptMap (ánh xạ giữa các code system).
• NamingSystem — đăng ký URI cho identifier (CCCD, BHYT, BHXH, mã hộ chiếu).
• CapabilityStatement — mô tả tập hợp Resource và operation mà server tuân thủ IG phải hỗ trợ.
• SearchParameter, OperationDefinition — tham số tìm kiếm và operation tùy chỉnh.
• Examples — instance JSON minh họa, validate được với chính các Profile của IG.
• Pagecontent — narrative markdown giải thích nghiệp vụ, hướng dẫn cài đặt, ví dụ workflow.

Quy trình build hai bước. Bước một: sushi . biên dịch FSH → StructureDefinition JSON, đặt vào fsh-generated/. Bước hai: IG Publisher (chạy qua script _genonce.sh) đọc sushi-config.yaml, ig.ini, fsh-generated, và pagecontent, tạo HTML site đầy đủ trong output/, kèm package .tgz để publish lên FHIR Package Registry. Output điển hình bao gồm index.html, qa.html (báo cáo QA), artifacts.html (danh mục mọi artifact), và file package.tgz để dependency của IG khác kéo về qua npm-style resolution.

IG có versioning theo SemVer, được khai báo trong sushi-config.yaml. Mọi IG khi tham chiếu IG khác đều phải pin version cụ thể (ví dụ [email protected]) để build deterministic.

7. Case study: VN Core IG

VN Core là Implementation Guide cho ngữ cảnh y tế Việt Nam do Omi HealthTech phát triển và đóng góp cho cộng đồng y tế số Việt Nam. Phiên bản hiện tại (theo sushi-config.yaml trong repo) là 0.8.0 với các thông số kỹ thuật:

Tập Profile bao quát các Resource trọng tâm cho hệ thống bệnh viện và BHYT: VNCorePatient, VNCorePractitioner, VNCorePractitionerRole, VNCoreOrganization, VNCoreOrganizationDepartment, VNCoreEncounter, VNCoreCondition, VNCoreObservation (với các specialization VitalSigns, BloodPressure, BodyHeight, BodyWeight, BodyTemperature, HeartRate, RespiratoryRate, SpO2, Lab, YHCT), VNCoreProcedure, VNCoreMedicationRequest, VNCoreMedicationDispense, VNCoreCoverage, VNCoreClaim, VNCoreClaimResponse, VNCoreExplanationOfBenefit, VNCorePaymentReconciliation, VNCoreImmunization, VNCoreAllergyIntolerance, VNCoreDevice, VNCoreImplantableDevice, VNCoreImagingStudy, VNCoreDiagnosticReport (với Lab, Imaging, Pathology variants), VNCoreDocumentReference, VNCoreComposition, VNCoreConsent, VNCoreProvenance, VNCoreAuditEvent, và bundle VNCoreBHYTSubmissionBundle phục vụ submission BHYT theo NĐ 164/2025/NĐ-CP.

Extension tập trung vào các trường nghiệp vụ Việt Nam mà FHIR base và các IG quốc tế chưa có: dân tộc, nghề nghiệp, tuyến chuyên môn kỹ thuật, hạng cơ sở khám chữa bệnh, loại đối tượng BHYT, kỳ thanh toán BHYT, lý do bất khả kháng cho định danh thiếu, phương thức consent, retention audit log, mã đăng ký lưu hành thiết bị y tế, nhóm rủi ro thiết bị y tế (loại A/B/C/D theo NĐ 98/2021/NĐ-CP), đơn vị hành chính cấp tỉnh/xã sau Nghị quyết 202/2025/QH15.

Terminology của VN Core gồm các CodeSystem nội địa: ICD-10 VN (theo QĐ 4469/QĐ-BYT), danh mục dân tộc 54 nhóm, danh mục đơn vị hành chính 34 tỉnh, danh mục mã đối tượng BHYT theo QĐ 3276/QĐ-BYT, danh mục thuật ngữ y học cổ truyền theo QĐ 2552/QĐ-BYT và 3080/QĐ-BYT, ConceptMap SNOMED CT VN theo QĐ 2427/2493/2805/QĐ-BYT.

8. So sánh quốc tế: US, JP, KR, CH, AU Core

VN Core tham chiếu nhiều IG quốc gia. Bảng dưới là snapshot trạng thái công bố được rà soát ngày 18/07/2026; không dùng số lượng Profile để xếp hạng độ trưởng thành hoặc mức công nhận:

Các IG có phạm vi và thẩm quyền khác nhau nên không thể suy ra độ trưởng thành từ số Profile. VN Core ưu tiên thêm lớp BHYT, KSK SDC và projection IPS vì đó là các use case trong phạm vi dự án; việc ánh xạ dữ liệu đầu ra BHYT sang FHIR vẫn là công việc adapter cần kiểm thử, không phải bằng chứng rằng một mô hình quốc tế khác “thiếu” hoặc rằng mọi nhà cung cấp HIS có cùng nghĩa vụ.

9. Câu hỏi thường gặp

Có bắt buộc viết Profile bằng FSH không?

Không. FSH là DSL hỗ trợ biên soạn, không phải định dạng bắt buộc của FHIR. Có thể viết StructureDefinition bằng JSON/XML hoặc sinh bằng công cụ khác; nhiều IG hiện đại chọn FSH vì thuận tiện cho diff và review, nhưng đây không phải quy tắc áp dụng cho mọi National Core IG.

Implementation Guide có versioning không?

Có. Mỗi IG công bố chính sách versioning riêng; VN Core dùng SemVer cho dòng phát hành dự án. Dependency package nên khai phiên bản cụ thể trong sushi-config.yaml để build tái lập được.

Có thể derive Profile từ Profile khác không?

Có. Một bệnh viện có thể derive BachMaiPatient từ VNCorePatient để thêm constraint riêng (ví dụ slice identifier mã bệnh án nội bộ với regex pattern cụ thể). Quy tắc bốn bất biến vẫn áp dụng: Profile con phải hợp lệ với mọi ràng buộc của Profile cha.

Khi nào nên tạo Extension mới và khi nào nên dùng extension chuẩn HL7?

Trước khi tạo extension, kiểm tra FHIR base, extension registry và IG đích. Tái sử dụng khi semantics, context, phiên bản và dependency phù hợp; không kéo extension từ một IG khác chỉ vì tên gần giống. VN Core dùng lại patient-birthPlace, patient-citizenship và patient-religion sau khi đối chiếu các điều kiện đó.

Must Support có nghĩa là bắt buộc có dữ liệu không?

Không. Must Support là yêu cầu cho hệ thống — phải có khả năng xử lý element. Cardinality mới quyết định một instance có bắt buộc chứa dữ liệu hay không. Một element 0..1 MS hợp lệ kể cả khi vắng mặt.

10. Tham chiếu và đọc tiếp

Tài liệu chuẩn HL7

• FHIR R4 — Profiling FHIR (§5.2)
• FHIR R4 — Conformance Rules: Must Support
• FHIR R4 — Address datatype definition
• FHIR R4 — JSON representation
• FSH School — FHIR Shorthand documentation
• US Core IG — STU 8
• JP Core IG
• CH Core IG
• AU Core IG

Văn bản pháp lý Việt Nam

• Thông tư 13/2025/TT-BYT — Bệnh án điện tử (ban hành 06/6/2025, hiệu lực 21/7/2025).
• Nghị định 102/2025/NĐ-CP — Quản lý dữ liệu y tế số (13/5/2025, hiệu lực 01/7/2025).
• Luật 91/2025/QH15 — Bảo vệ dữ liệu cá nhân (26/6/2025, hiệu lực 01/01/2026).
• Nghị quyết 202/2025/QH15 — Sắp xếp đơn vị hành chính cấp tỉnh (12/6/2025).
• Quyết định 4469/QĐ-BYT — ICD-10 VN (28/10/2020).
• Quyết định 3276/QĐ-BYT — Danh mục mã đối tượng đến KCB (17/10/2025).

Đọc tiếp trong knowledge hub