1. What is Implementation Guide?
Implementation Guide (IG) is a collection of rules, profiles, extensions, value sets, examples for a specific use case. The IG for Vietnam will define how to represent medical data according to Vietnamese standards.
| IG ingredients | Description | For example VN |
|---|---|---|
| Profiles | Binding for base resources | VN-Core-Patient (required CCCD) |
| Extensions | Add data elements | Health insurance number, Vietnamese ethnicity |
| ValueSets | Enabled code set | List of ethnic groups in Vietnam, ICD-10 Vietnam |
| CodeSystems | Code system | Province/city code, medical facility code |
| Examples | Sample example | Sample patient with CCCD and health insurance |
| CapabilityStatement | Server requirements | What minimum support is required? |
2. FSH — FHIR Shorthand
FSH is a domain-specific language that helps write FHIR Profiles many times more concise than JSON/XML.
# Cài đặt SUSHI (FSH compiler)
npm install -g fsh-sushi
# Tạo IG project mới
sushi init
Project structure
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 for Vietnam
Extension: Health insurance information
// 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: Ethnicity
// 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 and 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 and 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 with 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. Advanced IG — Invariants and 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. Summary
Implementation Guide — Set of rules, profiles, extensions for specific use cases
FSH (FHIR Shorthand) — Profile writing language is concise and easy to read
VN-Core-Patient — Profile Patient requires ID card, health insurance, full name, gender, date of birth
Extensions — Health insurance info (card number, place of registration, benefit level), Vietnamese ethnicity
CodeSystems/ValueSets — 54 ethnic groups, 63 provinces/cities, medical facility codes
SUSHI + IG Publisher — Build pipeline from FSH → JSON → HTML IG