VN Core Deep Dive

Terminology in VN Core: read codes before payloads

In FHIR, the wrong code may be more dangerous than the wrong JSON shape. VN Core v0.6.0 publishes 139 CodeSystems, 144 ValueSets, and 6 ConceptMaps so every code has a clear source, context, and meaning.

TL;DR

  • Do not validate with display. Machine meaning is carried by system + code + version; display is for humans and can vary by language.
  • CodeSystem is the code source, ValueSet is the contextual allowed set. A single CodeSystem can support many ValueSets.
  • Binding strength controls enforcement. required must use the ValueSet; extensible allows outside codes only when justified.
  • Version and validity need governance. Vietnam healthcare catalogs change through legal and technical publications, so avoid untraceable hard-coded values.

On this page

  1. Why terminology is a data-safety layer
  2. Six concepts to separate
  3. Terminology domains in VN Core
  4. Best practice for Coding.display
  5. Terminology implementation checklist

1. Why terminology is a data-safety layer

Profiles make payloads structurally valid; terminology makes them semantically valid. A Condition.code can be structurally valid while using the wrong code system. A code such as 01 may mean an ethnicity, a cost group, a document type, or a status depending on the system. VN Core therefore never treats code meaning as separate from the CodeSystem canonical URL.

In implementation, terminology should be treated as a data contract equal to profiles. HIS/EMR adapters should map local codes to standard CodeSystems at the boundary; servers should preserve system, code, and version when available; user interfaces can render display or text, but should not use them as keys.

2. Six concepts to separate

CodeSystem

The source definition of codes: code, display, designation, properties, and active/inactive status.

ValueSet

The allowed set of codes for a specific context; profiles bind coded elements to ValueSets.

ConceptMap

Mappings between code systems, for example ICD-10 VN to SNOMED CT or legacy catalogs to FHIR-native structures.

NamingSystem

Registered URIs for identifier systems such as CCCD, BHYT, BHXH, and MRN; not clinical code systems.

Coding.display

A human-facing label. Do not use display as a business key or validation criterion.

Version

The code-system or catalog version. Essential when Vietnamese legal or clinical catalogs change.

3. Terminology domains in VN Core

Domain Example code sets Related artifacts
Administration and demographics Province/commune, ethnicity, nationality, occupation, religion. Address, Patient, Organization
BHYT and output data Participant category, admission reason, treatment outcome, discharge status, cost group. Coverage, Claim, EOB, Invoice
Clinical ICD-10 VN, lab indicators, allergy, clinical finding, SNOMED CT VN. Condition, Observation, AllergyIntolerance
Health checkups Health checkup answer sets, health classification, form type, checkup observation codes. Questionnaire, QuestionnaireResponse, Observation
Traditional medicine Syndrome pattern, diagnosis, acupoint, technique, herb, prescription. Condition, Procedure, Medication
Legal and governance Legal reference codes and impact domains. Citation, Provenance, pagecontent, traceability

4. Best practice for Coding.display

Coding.display is useful for interfaces, logs, and human review, but it is not an identifier. The same system + code may have Vietnamese, English, or updated display labels. Conversely, the same display label may appear in different CodeSystems.

VN Core operating rule: send display when a reliable source is available, but receiving systems should not reject a payload only because display spelling differs or accents are missing when system + code is valid. Use CodeableConcept.text or narrative to preserve clinician-entered wording or service names at the time of documentation.

Production review rule: if a mapping rule compares display to decide business behavior, fix the rule. Compare system + code; render display.

5. Terminology implementation checklist

Every coded value carries `system`; do not send bare codes such as `01`, `DN`, or `I10`.
When the code system has a version, preserve `Coding.version` to reconstruct decisions at the time of recording.
Do not use `Coding.display` for validation, joins, or payment decisions.
Map local codes to standard CodeSystems at integration boundaries; do not leak local values into VN Core payloads without a clear NamingSystem or CodeSystem.
Check each element binding strength before deciding whether an out-of-ValueSet code is allowed.
Use clinically and legally reviewed ConceptMaps for ambiguous mappings; not every map is exact equivalence.
Open Terminology in the IG Next: Bundles and validation

VN Core Deep Dive Series

Move from overview to the IG in the right order.

These four pages orient readers before opening the normative IG: understand the artifact map, read Profiles, govern terminology, then validate Bundles and workflow payloads.

Artifact map

Profiles, terminology, capability, operations, examples, and package boundary.

How to read a Profile

Differential, snapshot, Must Support, slicing, binding, and extensions.

Terminology

Current

CodeSystems, ValueSets, ConceptMaps, NamingSystems, and Coding.display.

Bundles and validation

Bundles, examples, CapabilityStatements, OperationDefinitions, and go-live checks.
Open the normative IG Profiles Terminology Artifact Index