VN Core FHIR Implementation Guide — Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam
0.1.0 - STU1 Draft Viet Nam flag

VN Core FHIR Implementation Guide — Bộ Hướng dẫn Triển khai FHIR Cốt lõi cho Việt Nam - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Data Type Profile: Địa chỉ VN Core — VN Core Address Profile

Official URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-core-address Version: 0.1.0
Draft as of 2026-03-20 Computable Name: VNCoreAddress

Profile Address cho Việt Nam, hỗ trợ ĐVHC mới theo NQ 202/2025 (34 tỉnh, 3.321 xã). Bổ sung extension mã hóa tỉnh/TP và xã/phường. Cấp huyện (district) giữ lại cho backward-compatible nhưng KHÔNG Must Support — khuyến khích dùng extension:province + extension:ward. Căn cứ: NQ 202/2025/QH15, QĐ 19/2025/QĐ-TTg.

Usages:

You can also check for usages in the FHIR IG Statistics

Formal Views of Profile Content

Description of Profiles, Differentials, Snapshots and how the different presentations work.

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Address C 0..* Address An address expressed using postal conventions (as opposed to GPS or other location definition formats)
Constraints: vn-addr-province
... Slices for extension Content/Rules for all slices
.... extension:province S 0..1 Coding Mã tỉnh/thành phố (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province
Binding: Danh mục Tỉnh/Thành phố Việt Nam (active) — Vietnam Province ValueSet (extensible)
.... extension:ward S 0..1 Coding Mã xã/phường (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward
Binding: Danh mục Xã/Phường Việt Nam — Vietnam Ward/Commune ValueSet (extensible)
... use ?!Σ 0..1 code home | work | temp | old | billing - purpose of this address
Binding: AddressUse (required): The use of an address.
Example General: home
... text SΣ 0..1 string Địa chỉ đầy đủ dạng text
Example General: 137 Nowhere Street, Erewhon 9132
... district Σ 0..1 string Quận/Huyện (legacy — không còn chính thức sau NQ 202/2025)
Example General: Madison
... state SΣ 0..1 string Tên tỉnh/thành phố (text)
... postalCode Σ 0..1 string Mã bưu chính
Example General: 9132
... country Σ 0..1 string Quốc gia (mặc định VN)

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Address.use Base required AddressUse 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
vn-addr-province warning Address Địa chỉ Việt Nam (country = 'VN') phải có extension:province (mã tỉnh/TP) — theo mẫu CH Core ch-addr-2 country.empty() or country != 'VN' or extension.where(url = 'http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province').exists()

This structure is derived from Address

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Address C 0..* Address An address expressed using postal conventions (as opposed to GPS or other location definition formats)
Constraints: vn-addr-province
... Slices for extension Content/Rules for all slices
.... extension:province S 0..1 Coding Mã tỉnh/thành phố (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province
Binding: Danh mục Tỉnh/Thành phố Việt Nam (active) — Vietnam Province ValueSet (extensible)
.... extension:ward S 0..1 Coding Mã xã/phường (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward
Binding: Danh mục Xã/Phường Việt Nam — Vietnam Ward/Commune ValueSet (extensible)
... text S 0..1 string Địa chỉ đầy đủ dạng text
... line S 0..* string Số nhà, đường, thôn/ấp
... state S 0..1 string Tên tỉnh/thành phố (text)
... postalCode 0..1 string Mã bưu chính
... country 0..1 string Quốc gia (mặc định VN)

doco Documentation for this format

Constraints

Id Grade Path(s) Description Expression
vn-addr-province warning Address Địa chỉ Việt Nam (country = 'VN') phải có extension:province (mã tỉnh/TP) — theo mẫu CH Core ch-addr-2 country.empty() or country != 'VN' or extension.where(url = 'http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province').exists()
NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Address C 0..* Address An address expressed using postal conventions (as opposed to GPS or other location definition formats)
Constraints: vn-addr-province
... id 0..1 string Unique id for inter-element referencing
... Slices for extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... extension:province S 0..1 Coding Mã tỉnh/thành phố (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province
Binding: Danh mục Tỉnh/Thành phố Việt Nam (active) — Vietnam Province ValueSet (extensible)
.... extension:ward S 0..1 Coding Mã xã/phường (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward
Binding: Danh mục Xã/Phường Việt Nam — Vietnam Ward/Commune ValueSet (extensible)
... use ?!Σ 0..1 code home | work | temp | old | billing - purpose of this address
Binding: AddressUse (required): The use of an address.
Example General: home
... text SΣ 0..1 string Địa chỉ đầy đủ dạng text
Example General: 137 Nowhere Street, Erewhon 9132
... line SΣ 0..* string Số nhà, đường, thôn/ấp
This repeating element order: The order in which lines should appear in an address label
Example General: 137 Nowhere Street
... city Σ 0..1 string Name of city, town etc.
Example General: Erewhon
... district Σ 0..1 string Quận/Huyện (legacy — không còn chính thức sau NQ 202/2025)
Example General: Madison
... state SΣ 0..1 string Tên tỉnh/thành phố (text)
... postalCode Σ 0..1 string Mã bưu chính
Example General: 9132
... country Σ 0..1 string Quốc gia (mặc định VN)
... period Σ 0..1 Period Time period when address was/is in use
Example General: {"start":"2010-03-23","end":"2010-07-01"}

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Address.use Base required AddressUse 📍4.0.1 FHIR Std.
Address.type Base required AddressType 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
vn-addr-province warning Address Địa chỉ Việt Nam (country = 'VN') phải có extension:province (mã tỉnh/TP) — theo mẫu CH Core ch-addr-2 country.empty() or country != 'VN' or extension.where(url = 'http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province').exists()

This structure is derived from Address

Summary

Must-Support: 5 elements

Extensions

This structure refers to these extensions:

Key Elements View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Address C 0..* Address An address expressed using postal conventions (as opposed to GPS or other location definition formats)
Constraints: vn-addr-province
... Slices for extension Content/Rules for all slices
.... extension:province S 0..1 Coding Mã tỉnh/thành phố (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province
Binding: Danh mục Tỉnh/Thành phố Việt Nam (active) — Vietnam Province ValueSet (extensible)
.... extension:ward S 0..1 Coding Mã xã/phường (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward
Binding: Danh mục Xã/Phường Việt Nam — Vietnam Ward/Commune ValueSet (extensible)
... use ?!Σ 0..1 code home | work | temp | old | billing - purpose of this address
Binding: AddressUse (required): The use of an address.
Example General: home
... text SΣ 0..1 string Địa chỉ đầy đủ dạng text
Example General: 137 Nowhere Street, Erewhon 9132
... district Σ 0..1 string Quận/Huyện (legacy — không còn chính thức sau NQ 202/2025)
Example General: Madison
... state SΣ 0..1 string Tên tỉnh/thành phố (text)
... postalCode Σ 0..1 string Mã bưu chính
Example General: 9132
... country Σ 0..1 string Quốc gia (mặc định VN)

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Address.use Base required AddressUse 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
vn-addr-province warning Address Địa chỉ Việt Nam (country = 'VN') phải có extension:province (mã tỉnh/TP) — theo mẫu CH Core ch-addr-2 country.empty() or country != 'VN' or extension.where(url = 'http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province').exists()

Differential View

This structure is derived from Address

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Address C 0..* Address An address expressed using postal conventions (as opposed to GPS or other location definition formats)
Constraints: vn-addr-province
... Slices for extension Content/Rules for all slices
.... extension:province S 0..1 Coding Mã tỉnh/thành phố (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province
Binding: Danh mục Tỉnh/Thành phố Việt Nam (active) — Vietnam Province ValueSet (extensible)
.... extension:ward S 0..1 Coding Mã xã/phường (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward
Binding: Danh mục Xã/Phường Việt Nam — Vietnam Ward/Commune ValueSet (extensible)
... text S 0..1 string Địa chỉ đầy đủ dạng text
... line S 0..* string Số nhà, đường, thôn/ấp
... state S 0..1 string Tên tỉnh/thành phố (text)
... postalCode 0..1 string Mã bưu chính
... country 0..1 string Quốc gia (mặc định VN)

doco Documentation for this format

Constraints

Id Grade Path(s) Description Expression
vn-addr-province warning Address Địa chỉ Việt Nam (country = 'VN') phải có extension:province (mã tỉnh/TP) — theo mẫu CH Core ch-addr-2 country.empty() or country != 'VN' or extension.where(url = 'http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province').exists()

Snapshot View

NameFlagsCard.TypeDescription & Constraints    Filter: Filtersdoco
.. Address C 0..* Address An address expressed using postal conventions (as opposed to GPS or other location definition formats)
Constraints: vn-addr-province
... id 0..1 string Unique id for inter-element referencing
... Slices for extension 0..* Extension Additional content defined by implementations
Slice: Unordered, Open by value:url
.... extension:province S 0..1 Coding Mã tỉnh/thành phố (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province
Binding: Danh mục Tỉnh/Thành phố Việt Nam (active) — Vietnam Province ValueSet (extensible)
.... extension:ward S 0..1 Coding Mã xã/phường (QĐ 19/2025)
URL: http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-ward
Binding: Danh mục Xã/Phường Việt Nam — Vietnam Ward/Commune ValueSet (extensible)
... use ?!Σ 0..1 code home | work | temp | old | billing - purpose of this address
Binding: AddressUse (required): The use of an address.
Example General: home
... text SΣ 0..1 string Địa chỉ đầy đủ dạng text
Example General: 137 Nowhere Street, Erewhon 9132
... line SΣ 0..* string Số nhà, đường, thôn/ấp
This repeating element order: The order in which lines should appear in an address label
Example General: 137 Nowhere Street
... city Σ 0..1 string Name of city, town etc.
Example General: Erewhon
... district Σ 0..1 string Quận/Huyện (legacy — không còn chính thức sau NQ 202/2025)
Example General: Madison
... state SΣ 0..1 string Tên tỉnh/thành phố (text)
... postalCode Σ 0..1 string Mã bưu chính
Example General: 9132
... country Σ 0..1 string Quốc gia (mặc định VN)
... period Σ 0..1 Period Time period when address was/is in use
Example General: {"start":"2010-03-23","end":"2010-07-01"}

doco Documentation for this format

Terminology Bindings

Path Status Usage ValueSet Version Source
Address.use Base required AddressUse 📍4.0.1 FHIR Std.
Address.type Base required AddressType 📍4.0.1 FHIR Std.

Constraints

Id Grade Path(s) Description Expression
ele-1 error **ALL** elements All FHIR elements must have a @value or children hasValue() or (children().count() > id.count())
ext-1 error **ALL** extensions Must have either extensions or value[x], not both extension.exists() != value.exists()
vn-addr-province warning Address Địa chỉ Việt Nam (country = 'VN') phải có extension:province (mã tỉnh/TP) — theo mẫu CH Core ch-addr-2 country.empty() or country != 'VN' or extension.where(url = 'http://fhir.hl7.org.vn/core/StructureDefinition/vn-ext-province').exists()

This structure is derived from Address

Summary

Must-Support: 5 elements

Extensions

This structure refers to these extensions:

 

Other representations of profile: CSV, Excel, Schematron