Xem bản video
1. Implementation Guide là gì?
Implementation Guide (IG) là tập hợp các quy tắc, profiles, extensions, value sets, examples cho một use case cụ thể. IG cho Việt Nam sẽ định nghĩa cách biểu diễn dữ liệu y tế theo chuẩn Việt Nam.
| Thành phần IG | Mô tả | Ví dụ VN |
|---|---|---|
| Profiles | Ràng buộc cho base resources | VN-Core-Patient (bắt buộc CCCD) |
| Extensions | Thêm data elements | Số BHYT, dân tộc VN |
| ValueSets | Bộ mã cho phép | Danh mục dân tộc VN, ICD-10 VN |
| CodeSystems | Hệ thống mã | Mã tỉnh/thành, mã cơ sở KCB |
| Examples | Ví dụ mẫu | Patient mẫu với CCCD, BHYT |
| CapabilityStatement | Server requirements | Tối thiểu phải hỗ trợ gì |
2. FSH — FHIR Shorthand
FSH là ngôn ngữ domain-specific giúp viết FHIR Profiles ngắn gọn hơn JSON/XML gấp nhiều lần.
# Cài đặt SUSHI (FSH compiler)
npm install -g fsh-sushi
# Tạo IG project mới
sushi init
Cấu trúc Project
vn-core-ig/
├── sushi-config.yaml
├── input/
│ ├── fsh/
│ │ ├── profiles/
│ │ │ ├── VNCorePatient.fsh
│ │ │ ├── VNCoreOrganization.fsh
│ │ │ └── VNCoreEncounter.fsh
│ │ ├── extensions/
│ │ │ ├── BHYTExtension.fsh
│ │ │ └── EthnicityExtension.fsh
│ │ ├── valuesets/
│ │ │ ├── VNEthnicityVS.fsh
│ │ │ └── VNProvinceVS.fsh
│ │ ├── codesystems/
│ │ │ ├── VNEthnicityCS.fsh
│ │ │ └── VNProvinceCS.fsh
│ │ └── examples/
│ │ └── PatientExample.fsh
│ └── pagecontent/
│ └── index.md
└── ig.ini
sushi-config.yaml
id: vn.core
canonical: http://fhir.vn/ImplementationGuide/vn-core
name: VNCoreIG
title: Vietnam Core Implementation Guide
status: draft
version: 0.1.0
fhirVersion: 5.0.0
copyrightYear: 2025+
releaseLabel: ci-build
publisher:
name: Vietnam FHIR Community
url: https://fhir.vn
jurisdiction: urn:iso:std:iso:3166#VN "Vietnam"
dependencies:
hl7.fhir.r5.core: 5.0.0
3. VN-Core-Patient Profile
// input/fsh/profiles/VNCorePatient.fsh
Profile: VNCorePatient
Parent: Patient
Id: vn-core-patient
Title: "VN Core Patient"
Description: "Profile Patient cho hệ thống y tế Việt Nam"
// Bắt buộc có ít nhất 1 identifier (CCCD hoặc BHYT)
* identifier 1..* MS
* identifier ^slicing.discriminator.type = #pattern
* identifier ^slicing.discriminator.path = "system"
* identifier ^slicing.rules = #open
// Slice: CCCD
* identifier contains cccd 0..1 MS
* identifier[cccd].system = "http://fhir.vn/sid/cccd" (exactly)
* identifier[cccd].value 1..1
* identifier[cccd].value ^short = "Số Căn cước Công dân (12 số)"
// Slice: BHYT
* identifier contains bhyt 0..1 MS
* identifier[bhyt].system = "http://fhir.vn/sid/bhyt" (exactly)
* identifier[bhyt].value 1..1
* identifier[bhyt].value ^short = "Số thẻ Bảo hiểm Y tế"
// Họ tên bắt buộc
* name 1..* MS
* name.family 1..1 MS
* name.given 1..* MS
* name.text 1..1 MS
// Giới tính, ngày sinh bắt buộc
* gender 1..1 MS
* birthDate 1..1 MS
// Địa chỉ
* address MS
* address.city MS
* address.district MS
* address.state MS
* address.line MS
// Extensions
* extension contains
VNEthnicityExtension named ethnicity 0..1 MS and
VNBHYTExtension named bhytInfo 0..1 MS
4. Extensions cho Việt Nam
Extension: Thông tin BHYT
// input/fsh/extensions/BHYTExtension.fsh
Extension: VNBHYTExtension
Id: vn-bhyt-extension
Title: "VN BHYT Extension"
Description: "Thông tin bảo hiểm y tế Việt Nam"
Context: Patient
* extension contains
soThe 1..1 MS and
noiDangKy 1..1 MS and
ngayHieuLuc 1..1 MS and
ngayHetHan 0..1 MS and
mucHuong 1..1 MS
* extension[soThe].value[x] only string
* extension[soThe] ^short = "Số thẻ BHYT (15 ký tự)"
* extension[noiDangKy].value[x] only Reference(Organization)
* extension[noiDangKy] ^short = "Nơi đăng ký KCB ban đầu"
* extension[ngayHieuLuc].value[x] only date
* extension[ngayHieuLuc] ^short = "Ngày bắt đầu hiệu lực"
* extension[ngayHetHan].value[x] only date
* extension[ngayHetHan] ^short = "Ngày hết hạn"
* extension[mucHuong].value[x] only integer
* extension[mucHuong] ^short = "Mức hưởng BHYT (%)"
Extension: Dân tộc
// input/fsh/extensions/EthnicityExtension.fsh
Extension: VNEthnicityExtension
Id: vn-ethnicity-extension
Title: "VN Ethnicity Extension"
Description: "Dân tộc theo danh mục 54 dân tộc Việt Nam"
Context: Patient
* value[x] only CodeableConcept
* valueCodeableConcept from VNEthnicityVS (required)
5. CodeSystems và ValueSets
// input/fsh/codesystems/VNEthnicityCS.fsh
CodeSystem: VNEthnicityCS
Id: vn-ethnicity-cs
Title: "VN Ethnicity CodeSystem"
Description: "Danh mục 54 dân tộc Việt Nam (theo TCTK)"
* ^caseSensitive = true
* #01 "Kinh"
* #02 "Tày"
* #03 "Thái"
* #04 "Mường"
* #05 "Khmer"
* #06 "Hoa"
* #07 "Nùng"
* #08 "Hmông"
* #09 "Dao"
* #10 "Gia Rai"
// ... thêm 44 dân tộc còn lại
// input/fsh/valuesets/VNEthnicityVS.fsh
ValueSet: VNEthnicityVS
Id: vn-ethnicity-vs
Title: "VN Ethnicity ValueSet"
Description: "ValueSet cho 54 dân tộc Việt Nam"
* include codes from system VNEthnicityCS
// input/fsh/codesystems/VNProvinceCS.fsh
CodeSystem: VNProvinceCS
Id: vn-province-cs
Title: "VN Province CodeSystem"
Description: "63 tỉnh/thành phố Việt Nam"
* ^caseSensitive = true
* #01 "Hà Nội"
* #79 "TP. Hồ Chí Minh"
* #48 "Đà Nẵng"
* #31 "Hải Phòng"
* #92 "Cần Thơ"
// ... thêm các tỉnh/thành còn lại
6. Examples
// input/fsh/examples/PatientExample.fsh
Instance: VNPatientExample01
InstanceOf: VNCorePatient
Title: "Ví dụ: Bệnh nhân Nguyễn Văn A"
Description: "Ví dụ Patient tuân thủ VN-Core-Patient profile"
Usage: #example
* identifier[cccd].system = "http://fhir.vn/sid/cccd"
* identifier[cccd].value = "001234567890"
* identifier[bhyt].system = "http://fhir.vn/sid/bhyt"
* identifier[bhyt].value = "DN4012345678901"
* name[0].family = "Nguyễn"
* name[0].given[0] = "Văn"
* name[0].given[1] = "A"
* name[0].text = "Nguyễn Văn A"
* gender = #male
* birthDate = "1990-05-15"
* address[0].line[0] = "123 Nguyễn Huệ, Phường Bến Nghé"
* address[0].district = "Quận 1"
* address[0].city = "TP. Hồ Chí Minh"
* address[0].state = "79"
* address[0].country = "VN"
* extension[ethnicity].valueCodeableConcept = VNEthnicityCS#01 "Kinh"
* extension[bhytInfo].extension[soThe].valueString = "DN4012345678901"
* extension[bhytInfo].extension[noiDangKy].valueReference = Reference(Organization/org-bvdk-001)
* extension[bhytInfo].extension[ngayHieuLuc].valueDate = "2025-01-01"
* extension[bhytInfo].extension[ngayHetHan].valueDate = "2025-12-31"
* extension[bhytInfo].extension[mucHuong].valueInteger = 80
7. Build và Publish IG
# Compile FSH → FHIR JSON
sushi .
# Output:
# fsh-generated/
# resources/
# StructureDefinition-vn-core-patient.json
# StructureDefinition-vn-bhyt-extension.json
# CodeSystem-vn-ethnicity-cs.json
# ValueSet-vn-ethnicity-vs.json
# Patient-VNPatientExample01.json
# Chạy IG Publisher (cần Java 17+)
./_genonce.sh
# Hoặc dùng Docker
docker run --rm -v $(pwd):/ig \
hl7fhir/ig-publisher-base:latest \
java -jar /app/publisher.jar \
-ig /ig/ig.ini
Validate resources với IG
# Validate một resource
java -jar validator_cli.jar \
patient-example.json \
-ig vn-core-ig/output \
-profile http://fhir.vn/StructureDefinition/vn-core-patient
# Kết quả:
# Information: All OK (0 errors, 0 warnings)
8. IG nâng cao — Invariants và Constraints
// Thêm invariant cho CCCD (12 số)
Invariant: vn-cccd-format
Description: "Số CCCD phải có đúng 12 chữ số"
Expression: "value.matches('^[0-9]{12}$')"
Severity: #error
* identifier[cccd].value obeys vn-cccd-format
// Thêm invariant cho BHYT (15 ký tự)
Invariant: vn-bhyt-format
Description: "Số thẻ BHYT phải có đúng 15 ký tự"
Expression: "value.matches('^[A-Z]{2}[0-9]{13}$')"
Severity: #error
* identifier[bhyt].value obeys vn-bhyt-format
9. Tổng kết
Implementation Guide — Tập quy tắc, profiles, extensions cho use case cụ thể
FSH (FHIR Shorthand) — Ngôn ngữ viết profiles ngắn gọn, dễ đọc
VN-Core-Patient — Profile Patient bắt buộc CCCD, BHYT, họ tên, giới tính, ngày sinh
Extensions — BHYT info (số thẻ, nơi đăng ký, mức hưởng), dân tộc VN
CodeSystems/ValueSets — 54 dân tộc, 63 tỉnh/thành, mã cơ sở KCB
SUSHI + IG Publisher — Build pipeline từ FSH → JSON → HTML IG