# VN Core FHIR Implementation Guide for Vietnam > Full machine-readable extract for LLM consumption. Maintained alongside `llms.txt` > (short summary). Updated with each release. ## Quick facts - Project name: VN Core FHIR — Bộ Hướng dẫn Triển khai HL7 FHIR Cốt lõi cho Việt Nam - Maintainer: Omi HealthTech (Vietnam) - Status: Draft for Community Review (NOT yet an official HL7 Affiliate) - Latest version: 0.10.0 - FHIR base: R4 (4.0.1) - License: CC-BY-4.0 - Public website: https://hl7.org.vn - Canonical IG: https://fhir.hl7.org.vn - NPM package: hl7.fhir.vn.core@0.10.0 - Maintainer contact: info@hl7.org.vn - Repository: pending public governance handoff - Trademark: HL7® and FHIR® are trademarks of Health Level Seven International. VN Core is independent and not yet authorised by HL7 International as the official Vietnam Affiliate. ## Scope (v0.10.0) | Artifact | Count | |---|---| | Profiles | 99 | | Local extensions | 75 | | Total extensions (incl. 3 official Patient ext) | 78 | | CodeSystems | 207 | | ValueSets | 232 | | NamingSystems | 39 | | SearchParameters | 20 | | Logical models | 75 | | OperationDefinitions | 4 | | CapabilityStatements | 10 | | ConceptMaps | 25 | | Example files | 603 | | Example instances | 568 | | Total instances (resources + examples) | 825 | | Exported JSON artifacts | 1429 | | Vietnamese legal references (public registry) | 364 | | Legal reference CodeSystem concepts | 364 | | Legal domains | 18 | ## Why VN Core exists Vietnam's health information systems were built standard-by-standard and hospital-by-hospital, with different data shapes. This creates repeated mapping work across HIS-to-HIS, HIS-to-payer and HIS-to-citizen interfaces. VN Core publishes shared FHIR R4 constraints intended to reduce bespoke mapping; interoperability still depends on compatible capabilities, terminology, security and workflow contracts. VN Core is opinionated about three things: 1. **Citizen identity is CCCD-centred.** The 12-digit citizen ID issued by the Ministry of Public Security (TT 17/2024/TT-BCA) is the core citizen identifier. VNeID is an integration/authentication channel, not a parallel `Patient.identifier`; BHXH and BHYT identifiers are context-specific. 2. **Payment is BHYT-aware but not BHYT-only.** Coverage profiles reflect Vietnam's national health insurance (BHYT) under Decree 188/2025/NĐ-CP. The clinical core stays clean of payer-specific distortions; payer logic lives in a separate `BHYT Submission` package. 3. **Address is 2-tier.** Following Resolution 202/2025/QH15 (effective 01/07/2025), Vietnam restructured to 34 provinces and ~3,321 communes. Districts are deprecated in new data; legacy data can still be carried with explicit district extensions. ## Public website routes (https://hl7.org.vn/) ### Vietnamese (primary) - `/` — Homepage. Hero, why-FHIR, profile spotlight (Patient + Encounter + Coverage), international comparison, journey/roadmap teaser. - `/about/` — Project context, Omi HealthTech background, design decisions. - `/implementation/` — Three role-based playbooks: Hospital, Vendor/HIS, Government agency. - `/legal-framework/` — Searchable public v0.10.0 snapshot of 364 Vietnamese legal references across 18 legal domains. Each entry has status, effective timing and implementation impact; 357 have exact source links and 7 documented source exceptions remain under review. - `/roadmap/` — Product milestones (v0.1.0 → v1.0.0) alongside Vietnamese legal milestones. - `/governance/` — Operating principles, role structure, contribution process, three-stage path to HL7 Affiliate status. - `/community/` — Adoption KPI dashboard, pilot tracker, five open contributor roles. - `/news/` and `/news/{slug}/` — Changelog with RSS 2.0 feed at `/rss.xml`. - `/cite/` — BibTeX, APA 7, Vancouver, CITATION.cff for academic citation. - `/brand/` — Wordmark, palette, typography, asset downloads, trademark guidelines. - `/NOTICE.txt` — Short attribution, no-endorsement and third-party-rights notice for implementers and mirrors. - `/contact/` — Maintainer email + structured pilot intake mailto. - `/privacy-policy/`, `/terms/` — Vietnamese authoritative legal text under Law 91/2025 (Personal Data Protection) and Decree 356/2025/NĐ-CP. ### English (secondary, full parity for legal-framework + roadmap + governance + community + cite + brand + news + contact) - `/en/` — VN Core FHIR overview, current release facts, what VN Core covers. - `/en/about/` — About Omi HealthTech, why and how. - `/en/getting-started/` — Four-step onboarding: read IG, download package, pilot, contribute. - `/en/legal-framework/` — Full 364-reference parity with Vietnamese page. Status labels translated ("In force" / "Superseded" / "Future-effective"). Regulation codes kept in Vietnamese (TT/QĐ/NĐ/Luật) for legal precision; English translation of title/timing/note/impact. - `/en/roadmap/`, `/en/governance/`, `/en/community/`, `/en/cite/`, `/en/brand/`, `/en/news/`, `/en/contact/` — Full parity. - `/en/privacy-policy/`, `/en/terms/` — English summary; Vietnamese remains authoritative. ## Vietnamese-specific design choices ### Identifiers - **CCCD** (`http://fhir.hl7.org.vn/core/sid/cccd`) — 12-digit citizen ID; core citizen identifier. - **BHYT** (`http://fhir.hl7.org.vn/core/sid/bhyt`) — either the current 10-digit BHYT number or the legacy 15-character card number (`2` uppercase letters + `13` digits). A 12-digit CCCD is not valid in this namespace. - **CMND** (`http://fhir.hl7.org.vn/core/sid/cmnd`) — legacy 9-digit identity number. - **BHXH** (`http://fhir.hl7.org.vn/core/sid/bhxh`) — 10-digit social-insurance number. - **GPHN** — practice licence, the current credential under the Law on Medical Examination and Treatment 15/2023/QH15 (which uses "giấy phép hành nghề" throughout). - **CCHN** — the pre-2024 practising certificate. Article 121 of Law 15/2023/QH15 converts it to a GPHN on a government-set schedule; Decree 96/2023/NĐ-CP Art. 143.2 lets it stand in for a GPHN until converted. Kept in VN Core as a transitional identifier, not as the current credential. - **Hospital MRN** — local, system-defined. ### Address Following NQ 202/2025/QH15 + QĐ 19/2025/QĐ-TTg: - 34 provinces (26 provinces + 8 centrally-administered cities as of release 0.10.0; the 2025 reorganization started at 28 + 6, with Đồng Nai and Quảng Ninh upgraded in 2026) - ~3,321 commune-level units (xã/phường/đặc khu) - Districts (huyện) are deprecated; only kept for historical data via the `vn-ext-district-legacy` extension when round-tripping legacy systems. `Address.state` carries the province/city display; `vn-ext-province` carries the structured province code and `vn-ext-ward` carries the structured commune/ward/special-zone code. `Address.district` is retained only for legacy round-tripping. ### BHYT (national health insurance) - `Coverage.identifier[BHYT]` is `0..1` within the open `identifier` slice and accepts only the current 10-digit BHYT number or the legacy 15-character card number. - `Coverage.type` is constrained to the standard `medical` coverage category. - `Coverage.payor` remains `1..*`; implementations record the responsible payer Organization rather than relying on an implicit fixed reference. - `vn-ext-bhyt-card-type` represents the participant/card group; it does not carry `MA_DOITUONG_KCB`, which belongs on `Claim.subType`. - `vn-ext-primary-care-facility` represents the registered primary-care facility (`MA_DKBD`). - `vn-ext-coverage-cumulative-copay` carries the cumulative annual copayment amount. - `Coverage.period` is `0..1`; start and end are Must Support when known. ### Clinical terminologies - **ICD-10 VN** — edition 2026 under TT 06/2026/TT-BYT (16,052 concepts, effective 01/07/2026); the 2020 edition (QĐ 4469/QĐ-BYT) is superseded and kept only as historical provenance, with the COVID-19 codes added by QĐ 98/QĐ-BYT (2022). - **DVKT** (technical service catalogue) under TT 23/2024/TT-BYT (replaced TT 43/2013/TT-BYT). - **SNOMED CT VN** — 3 batches translated and adopted: Body Structure (QĐ 2427/QĐ-BYT), Morphologic Abnormality (QĐ 2493/QĐ-BYT), Allergy + Finding (QĐ 2805/QĐ-BYT). - **Traditional medicine (YHCT)** — QĐ 2552/QĐ-BYT (batch 1: clinical pattern, diagnosis, acupoints, techniques) + QĐ 3080/QĐ-BYT (batch 2: symptoms, tongue, pulse, treatment principles, herbs, formulas). - **Lab indicators** — QĐ 1227/QĐ-BYT (2,964 indicators across hematology, biochemistry, microbiology, pathology, imaging). ## Package architecture VN Core ships as 9 NPM packages so payer-specific logic stays out of the clinical core: 1. `hl7.fhir.vn.core` — top-level aggregate package 2. `hl7.fhir.vn.core.base` — clinical core (Patient, Encounter, Condition, Observation, ...) 3. `hl7.fhir.vn.pharmacy` — ePrescription, dispensing, national pharmacy-database exchange 4. `hl7.fhir.vn.bhyt.submission` — payer-side: Claim, ExplanationOfBenefit, BHYT-specific extensions, 16 logical models (`Check-in`, `XML1`–`XML15`) and three BHYT operations; QĐ 4210 is historical context while current mapping follows the later output-data chain 5. `hl7.fhir.vn.patient-access` — citizen-facing access (VNeID health book, health checkup) 6. `hl7.fhir.vn.terminology.clinical` — modern clinical terminologies (ICD-10 VN, SNOMED VN, lab) 7. `hl7.fhir.vn.terminology.traditional-medicine` — Vietnamese traditional medicine codes 8. `hl7.fhir.vn.device` — medical device profiles and registration/class terminology (NĐ 98/2021/NĐ-CP chain, class A/B/C/D, TT 24/2025/TT-BYT BHYT device groups) 9. `hl7.fhir.vn.legal` — machine-readable legal registry (VNLegalDocumentRefCS + effectivity) ## Major regulatory drivers - **Identity**: NQ 202/2025/QH15 (34 provinces, 01/07/2025), QĐ 19/2025/QĐ-TTg (commune codes), TT 17/2024/TT-BCA (citizen ID validation). - **EMR**: TT 13/2025/TT-BYT (mandatory electronic medical records, effective 21/07/2025); Law 15/2023/QH15 (Medical Examination and Treatment); QĐ 586/QĐ-BYT (national EMR rollout 2026). - **Privacy**: Law 91/2025/QH15 (Personal Data Protection, effective 01/01/2026); Decree 356/2025/NĐ-CP (DPIA, DPO, 72-hour breach notification); Law 116/2025/QH15 (Cybersecurity, effective 01/07/2026). - **BHYT**: QĐ 3176/QĐ-BYT (current data exchange schema, 2024); QĐ 697/QĐ-BYT (new cost itemisation form, effective 01/07/2026); NĐ 188/2025/NĐ-CP (benefit levels); NĐ 164/2025/NĐ-CP (electronic transactions). - **Pharmacy / devices**: NĐ 163/2025/NĐ-CP (pharmacy law guidance, replaces NĐ 54/2017/NĐ-CP); TT 26/2025/TT-BYT (e-prescription); NĐ 07/2023/NĐ-CP + NĐ 04/2025/NĐ-CP (medical device chain amending NĐ 98/2021/NĐ-CP); TT 24/2025/TT-BYT (9 BHYT device groups N01-N09). ## Path to HL7 Affiliate (transparent positioning) VN Core is **not** currently authorised by HL7 International as the official Vietnam Affiliate. The path: 1. **Active (now, 2026)** — Trial-use draft maintained openly by Omi HealthTech. 2. **Planned (2026-2027)** — Working group formalisation: steering roles, disclosed or review-eligible pilots, conformance testing infrastructure, and an evidence package. 3. **Future (2027+)** — Prepare an HL7 Vietnam Affiliate filing with HL7 International if governance conditions and stakeholder alignment are met. Recognition is earned through work, not the other way around. ## Reuse, attribution and rights boundaries VN Core-authored content is published under CC-BY-4.0. Suggested attribution: `VN Core FHIR Implementation Guide v0.10.0 — Omi HealthTech / VN Core FHIR Community Initiative — https://hl7.org.vn`. Commercial use, internal redistribution and derivative implementation guides are allowed with attribution and change notices. Do not imply endorsement by Omi HealthTech, the VN Core community, HL7 International or any Vietnamese state agency. Rights and licensing boundaries: - HL7(R) and FHIR(R) are trademarks of Health Level Seven International. - HL7 base specifications are governed by HL7's own licence terms. - LOINC content is governed by the Regenstrief Institute LOINC licence. - SNOMED CT content is governed by SNOMED International licence terms. - Vietnamese legal documents and Thư Viện Pháp Luật source pages are cited for traceability; VN Core does not relicense those sources. - Implementers remain responsible for clinical safety, legal compliance and local validation before production use. ## Pilot status (as of v0.10.0) - Public confirmed pilots: 0 (confidential pilots are not listed until naming is approved) - Open pilot slots: 3 (provincial public hospital, commercial HIS, BHXH integration partner) - Contributing organisations: 1 (Omi HealthTech, maintainer) - Contributor roles open: 5 (clinical SME, terminologist, FHIR engineer, legal/compliance, integration partner) Updates via `governance/community-tracker.json` → synced to site at build time. ## How to contribute 1. Read the IG at https://fhir.hl7.org.vn — start with Patient, Encounter, Coverage. 2. Find a gap: missing extension, stale legal reference, missing example, profile-vs-workflow mismatch. 3. Email the maintainer at info@hl7.org.vn with a structured proposal: problem statement, affected artifact, legal basis (TT/QĐ/NĐ/Luật reference) or clinical justification, and example data when available. 4. The maintainer triages the proposal, records the evidence, validates accepted changes, and schedules them for release under the governance process. CC-BY-4.0 contribution agreement is implicit. ## Citation ```bibtex @software{vncore_fhir_0_8_0, title = {VN Core FHIR Implementation Guide for Vietnam}, author = {{Omi HealthTech}}, year = {2026}, month = {7}, version = {0.10.0}, url = {https://hl7.org.vn}, note = {Trial-use draft, CC-BY-4.0} } ``` VN Core does not currently have a DOI. Cite the URL, version and access date; a release-specific DOI may be registered after a durable publication and archival process is established. ## Contact - Email: info@hl7.org.vn (general inquiries, contributions) - Pilot intake: info@hl7.org.vn - Omi HealthTech: https://omihealthtech.vn - HL7 International: https://www.hl7.org/ (for trademark and Affiliate questions)