xDev Asia

FHIR architecture (Resources, Data Types, Extensibility, RESTful API, Messaging, Documents), 80/20 design principles, FHIR Maturity Model (FMM), comparison of FHIR R4 vs R5, modules in specification.

HL7 FHIR - Basic to Advanced Healthcare Data Standard

Part 1: HL7 and FHIR Platform

xdev.asia

1. Overall architecture of FHIR

FHIR is designed as one platform. platform — not just a data standard but a complete ecosystem for health information exchange. The FHIR architecture includes the following layers:

Architectural floors

┌─────────────────────────────────────────┐
│     Implementation Guides (IGs)         │  ← Tùy chỉnh cho ngữ cảnh
├─────────────────────────────────────────┤
│   Profiles / Extensions / Terminologies │  ← Ràng buộc & mở rộng
├─────────────────────────────────────────┤
│   Exchange (REST / Messaging / Docs)    │  ← Cách trao đổi dữ liệu
├─────────────────────────────────────────┤
│          Resources (~157 loại)          │  ← Đơn vị dữ liệu
├─────────────────────────────────────────┤
│         Data Types (Primitive/Complex)  │  ← Kiểu dữ liệu
├─────────────────────────────────────────┤
│      Foundation (Infrastructure)        │  ← Nền tảng chung
└─────────────────────────────────────────┘

2. Resource — The basic unit of FHIR

In FHIR, everything is represented as Resource. Resources are basic building blocks — like "tables" in a relational database, but much more flexible.

Common characteristics of all Resources

All Resources have:

id — logical identifier, unique within the server
meta. meta — metadata (versionId, lastUpdated, profile, security, tag)
implicitRules — reference to special handling rules (rarely used)
language. language — language of the resource

Most Resources are DomainResource (inherit from Resource), add:

text. text — Narrative (human-readable HTML part)
contained. contained — Resources embedded inside
extension — extended data
modifierExtension — extension changes the semantics of Resource

Example: Patient Resource (JSON)

{
  "resourceType": "Patient",
  "id": "example-vn",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2026-03-30T10:00:00Z"
  },
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\">Nguyễn Văn A, Nam, 15/03/1985</div>"
  },
  "identifier": [
    {
      "system": "urn:oid:2.16.840.1.113883.4.56.10",
      "value": "001085012345"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Nguyễn",
      "given": ["Văn", "A"]
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "line": ["123 Lê Lợi"],
      "city": "Thành phố Hồ Chí Minh",
      "country": "VN"
    }
  ]
}

157 Resources are classified by modules

FHIR R5 has 157 resource types, organized into modules:

Module	Description	Typical Resources
Foundation	Basic infrastructure	Bundle, OperationOutcome, Binary, Parameters
Conformance	Conformance specification	CapabilityStatement, StructureDefinition, SearchParameter
Terminology	Terminology	CodeSystem, ValueSet, ConceptMap
Security	Security	Provenance, AuditEvent, Consent, Permission
Administration	Administration	Patient, Practitioner, Organization, Location, Encounter
Clinical	Clinical	Condition, Observation, AllergyIntolerance, Procedure
Diagnostics	Diagnosis	DiagnosticReport, Specimen, ImagingStudy
Medications	Medicine	Medication, MedicationRequest, Immunization
Workflow	Process	Task, Appointment, Schedule, ServiceRequest
Financial	Finance	Claim, Coverage, ExplanationOfBenefit

3. 80/20 design principle

FHIR applies the philosophy: Addresses 80% of common use cases in the basic standard, allowing the remaining 20% through extensions and profiles.

This means:

The basic resource is simple enough — don't try to cram in every special case
Extension mechanism — when you need more data, use Extensions instead of standard changes
Profile — when tighter constraints are needed, use StructureDefinition

For example, the basic Resource Patient does not have a "CCCD number" field (only used in Vietnam), but you can add it via Extension or use identifier with the appropriate system.

4. Three data exchange paradigms

FHIR supports 3 ways of data exchange, suitable for different situations:

4.1. RESTful APIs

The most common way, based on HTTP methods:

# Đọc thông tin bệnh nhân
GET /Patient/123

# Tạo bệnh nhân mới
POST /Patient
Content-Type: application/fhir+json
{...}

# Cập nhật
PUT /Patient/123
{...}

# Tìm kiếm
GET /Patient?family=Nguyen&birthdate=1985-03-15

# Xóa
DELETE /Patient/123

Use when: Web/mobile applications, patient portals, data queries, SMART apps.

4.2. Messaging

Sending messages between systems (similar to HL7 v2 but using FHIR Resources):

{
  "resourceType": "Bundle",
  "type": "message",
  "entry": [
    {
      "resource": {
        "resourceType": "MessageHeader",
        "eventCoding": {
          "system": "http://example.org/events",
          "code": "admit-notification"
        },
        "source": { "endpoint": "http://hospital-a.vn/fhir" }
      }
    },
    {
      "resource": {
        "resourceType": "Patient",
        "id": "123"
      }
    }
  ]
}

Use when: Event-driven exchange (hospital admission, discharge, test results), integration with legacy systems.

4.3. Documents

Create structured medical documents (similar to CDA but using FHIR):

{
  "resourceType": "Bundle",
  "type": "document",
  "entry": [
    {
      "resource": {
        "resourceType": "Composition",
        "title": "Tóm tắt xuất viện",
        "type": {
          "coding": [{
            "system": "http://loinc.org",
            "code": "18842-5",
            "display": "Discharge summary"
          }]
        },
        "section": [...]
      }
    }
  ]
}

Use when: Hospital discharge papers, medical history summaries, referral papers, International Patient Summary.

5. FHIR Maturity Model (FMM)

Each Resource in FHIR has a maturity level (FMM) from 0 to Normal (N):

FMM	Level	Meaning
0	Draft	Just proposed, not yet implemented
1	Draft (tested)	There is at least 1 implementation
2	Trial Use	Tested at Connectathon
3	Trial Use (verified)	There have been many practical implementations
4	Trial Use (agreed)	Quality criteria met, standard preparation
5	Trial Use (published)	Published in 2+ ballot cycles
N	Normative	Stable, backward compatible — NO change

Some Resources have been reached Normative in R5:

Patient (N), Observation (N), Bundle (N), CapabilityStatement (N)
StructureDefinition (N), ValueSet (N), CodeSystem (N)
OperationOutcome (N), Binary (N), Parameters (N)

When choosing Resources for a project, priority should be given to Resources with FMM ≥ 3 or Normal to ensure stability.

6. FHIR R4 vs R5 — Important changes

R4 is still the most used version (because many mandates in the US are based on R4). R5 brings many improvements:

Features	R4	R5
Subscriptions	Criteria-based subscription	Topic-based Subscriptions (SubscriptionTopic)
Workflow	Task basic	New Transport resource, improved workflow patterns
Evidence-Based Med	Limitations	new Evidence, EvidenceVariable, ArtifactAssessment
New Resources	—	Permission, InventoryItem, InventoryReport, NutritionIntake
Observation	component-based	Improvements triggeredBy, instantiatesCanonical
Search	Standard	_filter, _sort enhancements
Types	—	CodeableReference(new), integer64

Recommendation:

New project in the US: use R4 (because of US Core mandate)
New non-binding project: considerations R5 (newer, more features)
Project in Vietnam: R4 or R5 are all suitable (no specific mandate yet)

7. Modules in the FHIR Specification

FHIR specification is organized into main modules:

Foundation Module

Technical foundation: Resource definition, Data Types, Extensions, REST API, Messaging, Documents, Narrative, Compartments.

Implementer Support Module

Deployment support: Downloads, testing tools, implementation guides registry, validation.

Security & Privacy Module

Security: Authorization, Authentication, Security labels, Audit, Consent, Provenance.

Conformance Module

Conformance specification: CapabilityStatement, StructureDefinition, OperationDefinition, SearchParameter, Implementation Guides.

Terminology Module

Terminology: CodeSystem, ValueSet, ConceptMap, NamingSystem, terminology operations ($validate-code, $expand, $lookup, $translate).

Administration Module

Administrative management: Patient, Practitioner, Organization, Location, HealthcareService, Endpoint, Device.

Clinical Modules

Clinical Modules include: Clinical Summary (Condition, AllergyIntolerance, Procedure), Diagnostics (Observation, DiagnosticReport), Medications, Care Provision (CarePlan, Goal), Workflow (Task, Appointment).

Financial Module

Medical finance: Coverage, Claim, ExplanationOfBenefit, Account, Invoice.

8. Resource References — Links between Resources

Resources in FHIR are linked together References. This is the most important mechanism to create a medical data network.

{
  "resourceType": "Observation",
  "id": "blood-pressure",
  "status": "final",
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "85354-9",
      "display": "Blood pressure panel"
    }]
  },
  "subject": {
    "reference": "Patient/example-vn",
    "display": "Nguyễn Văn A"
  },
  "encounter": {
    "reference": "Encounter/visit-2026-03-30"
  },
  "performer": [{
    "reference": "Practitioner/dr-tran"
  }],
  "effectiveDateTime": "2026-03-30T09:00:00+07:00",
  "component": [
    {
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "8480-6",
          "display": "Systolic blood pressure"
        }]
      },
      "valueQuantity": {
        "value": 120,
        "unit": "mmHg",
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      }
    },
    {
      "code": {
        "coding": [{
          "system": "http://loinc.org",
          "code": "8462-4",
          "display": "Diastolic blood pressure"
        }]
      },
      "valueQuantity": {
        "value": 80,
        "unit": "mmHg",
        "system": "http://unitsofmeasure.org",
        "code": "mm[Hg]"
      }
    }
  ]
}

In the example above:

subject. subject → link to Patient
encounter. encounter → link to Encounter (visit)
performer → link to Practitioner (doctor measures)

9. Narrative — Human-readable part

Each DomainResource can contain sections Narrative — HTML represents resource content that humans can read. This is an important feature for clinical safety:

{
  "text": {
    "status": "generated",
    "div": "<div xmlns='http://www.w3.org/1999/xhtml'><p>Huyết áp: 120/80 mmHg</p><p>Bệnh nhân: Nguyễn Văn A</p><p>Ngày đo: 30/03/2026</p></div>"
  }
}

Narrative status can be:

generated — created from structured data
extensions — contains information from extensions
additional. additional — has additional information that is not included in the structured data
empty — no content (in contained resources)

10. Extensibility — Extensibility mechanism of FHIR

This is one of FHIR's strongest features. When you need additional data that is not in the standard, you use it Extensions:

{
  "resourceType": "Patient",
  "id": "vn-patient",
  "extension": [
    {
      "url": "http://fhir.vn/StructureDefinition/patient-ethnicity",
      "valueCodeableConcept": {
        "coding": [{
          "system": "http://fhir.vn/CodeSystem/vn-ethnicity",
          "code": "01",
          "display": "Kinh"
        }]
      }
    },
    {
      "url": "http://fhir.vn/StructureDefinition/patient-cccd",
      "valueString": "001085012345"
    }
  ],
  "name": [{"family": "Nguyễn", "given": ["Văn", "A"]}]
}

Two important rules:

The receiving system MUST be able to read the resource even if you don't understand extension (graceful handling)
Extensions MUST NOT change semantics of base elements (except modifierExtension)

11. Summary

In this article, we learned:

FHIR architecture includes many layers: Foundation → Data Types → Resources → Exchange → Profiles → IGs
Resource As the basic unit, FHIR R5 has 157 resource types
80/20 rule: basic standard solves 80%, extensions give 20%
3 paradigms: REST (most popular), Messaging, Documents
FMM: assess maturity level, prioritize Resources Normative
R4 vs R5: R4 is more stable, R5 has many new features
References: how to link Resources into a data network
Narrative: human-readable HTML section for clinical safety
Extensibility: flexible extensibility mechanism without breaking the standard

Next lesson, we will Practice setting up the environment: HAPI FHIR Server, Postman, FHIR tools — and test your first CRUD operations.

Lesson 2: Overview of FHIR R5 - Architecture and design principles