xDev Asia

Resource Patient details (demographics, identifiers, contact, link), Practitioner and PractitionerRole, Organization, Location, Endpoint. Practice creating, reading, and updating Patients on FHIR Server.

HL7 FHIR - Basic to Advanced Healthcare Data Standard

Part 2: Core FHIR Resources

xdev.asia

1. Patient Resource — Medical data center

Patient is the most important Resource in FHIR — almost all clinical data is associated with a Patient. This is also the first Resource to level up Normative (stable, backward-compatible).

Patient Resource structure

Element	Type	Cardinality	Description
identifier	Identifier[]	0..*	Identifier code (CCCD, health insurance, MRN...)
active	boolean	0..1	Is recording active?
name	HumanName[]	0..*	Patient's full name
telecom	ContactPoint[]	0..*	Phone number, email
gender	code	0..1	male \| female \| other \| unknown. unknown
birthDate	date. date	0..1	Date of birth
deceased[x]	boolean/dateTime	0..1	Lost?
address	Address[]	0..*	Address
maritalStatus	CodeableConcept	0..1	Marital status
multipleBirth[x]	boolean/integer	0..1	Twins/triplets?
photo. photo	Attachment[]	0..*	Representative photo
contact. contact	BackboneElement[]	0..*	Contact person
communication. communication	BackboneElement[]	0..*	Communication language
generalPractitioner	Reference[]	0..*	Primary care physician
managingOrganization	Reference	0..1	Organize records management
link. link	BackboneElement[]	0..*	Link to another record (merge)

Patient Resource for Vietnamese patients — Full example

{
  "resourceType": "Patient",
  "id": "vn-patient-001",
  "meta": {
    "profile": ["http://fhir.vn/StructureDefinition/vn-core-patient"]
  },
  "identifier": [
    {
      "use": "official",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "NI",
          "display": "National unique individual identifier"
        }]
      },
      "system": "http://fhir.vn/sid/cccd",
      "value": "001085012345"
    },
    {
      "use": "secondary",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "SB",
          "display": "Social Beneficiary Identifier"
        }]
      },
      "system": "http://fhir.vn/sid/bhyt",
      "value": "DN4850112340001"
    },
    {
      "use": "usual",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "MR",
          "display": "Medical record number"
        }]
      },
      "system": "http://benhvien-a.vn/sid/mrn",
      "value": "BN-2026-00123"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "text": "Nguyễn Văn An",
      "family": "Nguyễn",
      "given": ["Văn", "An"]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "+84901234567",
      "use": "mobile",
      "rank": 1
    },
    {
      "system": "email",
      "value": "[email protected]",
      "use": "home"
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "text": "123 Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM",
      "line": ["123 Lê Lợi"],
      "city": "Thành phố Hồ Chí Minh",
      "district": "Quận 1",
      "state": "Thành phố Hồ Chí Minh",
      "postalCode": "700000",
      "country": "VN"
    }
  ],
  "maritalStatus": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-MaritalStatus",
      "code": "M",
      "display": "Married"
    }],
    "text": "Đã kết hôn"
  },
  "contact": [
    {
      "relationship": [{
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
          "code": "N",
          "display": "Next-of-Kin"
        }]
      }],
      "name": {
        "text": "Trần Thị Bình",
        "family": "Trần",
        "given": ["Thị", "Bình"]
      },
      "telecom": [{
        "system": "phone",
        "value": "+84907654321"
      }]
    }
  ],
  "communication": [{
    "language": {
      "coding": [{
        "system": "urn:ietf:bcp:47",
        "code": "vi",
        "display": "Vietnamese"
      }]
    },
    "preferred": true
  }],
  "managingOrganization": {
    "reference": "Organization/benhvien-a",
    "display": "Bệnh viện Đại học Y Dược TP.HCM"
  }
}

Identifier Patterns for Vietnam

ID type	System (URL)	Value example
Citizen identification card (CCCD)	http://fhir.vn/sid/cccd	001085012345
Health insurance card	http://fhir.vn/sid/bhyt	DN4850112340001
Patient code (MRN)	http://benhvien.vn/sid/mrn	BN-2026-00123
Passport	http://fhir.vn/sid/passport	C1234567

2. Practitioner Resource — Medical staff

Practitioner represents any individual involved in health care: doctors, nurses, pharmacists, technicians...

{
  "resourceType": "Practitioner",
  "id": "dr-tran-001",
  "identifier": [{
    "system": "http://fhir.vn/sid/physician-license",
    "value": "BS-TPHCM-2010-00456"
  }],
  "active": true,
  "name": [{
    "use": "official",
    "text": "TS.BS Trần Minh Đức",
    "family": "Trần",
    "given": ["Minh", "Đức"],
    "prefix": ["TS.BS"]
  }],
  "telecom": [{
    "system": "phone",
    "value": "+84909876543",
    "use": "work"
  }],
  "gender": "male",
  "birthDate": "1978-05-20",
  "qualification": [
    {
      "identifier": [{
        "system": "http://fhir.vn/sid/medical-degree",
        "value": "BSCK2-NKH-2010"
      }],
      "code": {
        "coding": [{
          "system": "http://fhir.vn/CodeSystem/qualification",
          "code": "BSCK2",
          "display": "Bác sĩ Chuyên khoa II"
        }]
      },
      "issuer": {
        "display": "Đại học Y Dược TP.HCM"
      }
    }
  ],
  "communication": [{
    "coding": [{
      "system": "urn:ietf:bcp:47",
      "code": "vi"
    }]
  }]
}

PractitionerRole — Specific role

PractitionerRole Describes the role of a Practitioner at a specific Organization. A doctor can have many PractitionerRoles (work in many places).

{
  "resourceType": "PractitionerRole",
  "id": "dr-tran-role-bva",
  "active": true,
  "practitioner": {
    "reference": "Practitioner/dr-tran-001",
    "display": "TS.BS Trần Minh Đức"
  },
  "organization": {
    "reference": "Organization/benhvien-a",
    "display": "Bệnh viện A"
  },
  "code": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/practitioner-role",
      "code": "doctor",
      "display": "Doctor"
    }]
  }],
  "specialty": [{
    "coding": [{
      "system": "http://snomed.info/sct",
      "code": "394579002",
      "display": "Cardiology"
    }],
    "text": "Tim mạch"
  }],
  "location": [{
    "reference": "Location/phong-kham-tim-mach"
  }],
  "availableTime": [{
    "daysOfWeek": ["mon", "tue", "wed", "thu", "fri"],
    "availableStartTime": "07:30:00",
    "availableEndTime": "16:30:00"
  }]
}

3. Organization Resource — Medical facility

{
  "resourceType": "Organization",
  "id": "benhvien-a",
  "identifier": [
    {
      "system": "http://fhir.vn/sid/facility-code",
      "value": "79001"
    },
    {
      "system": "http://fhir.vn/sid/bhxh-facility",
      "value": "79-001"
    }
  ],
  "active": true,
  "type": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/organization-type",
      "code": "prov",
      "display": "Healthcare Provider"
    }]
  }],
  "name": "Bệnh viện Đại học Y Dược TP.HCM",
  "alias": ["BV ĐHYD"],
  "telecom": [
    {
      "system": "phone",
      "value": "+842838554269",
      "use": "work"
    },
    {
      "system": "url",
      "value": "https://www.bvdhydtphcm.vn"
    }
  ],
  "address": [{
    "use": "work",
    "line": ["215 Hồng Bàng"],
    "city": "Thành phố Hồ Chí Minh",
    "district": "Quận 5",
    "country": "VN"
  }]
}

4. Location Resource — Location

Location Describe the physical location: clinic, department, hospital bed, operating room...

{
  "resourceType": "Location",
  "id": "phong-kham-tim-mach",
  "status": "active",
  "name": "Phòng khám Tim mạch - Tầng 3",
  "description": "Phòng khám chuyên khoa Tim mạch, tầng 3 tòa nhà B",
  "mode": "instance",
  "type": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-RoleCode",
      "code": "CARD",
      "display": "Ambulatory Health Care Facilities; Clinic/Center; Rehabilitation: Cardiac Facilities"
    }]
  }],
  "telecom": [{
    "system": "phone",
    "value": "+842838554269-303"
  }],
  "address": {
    "line": ["Tầng 3, Tòa B, 215 Hồng Bàng"],
    "city": "TP.HCM",
    "country": "VN"
  },
  "physicalType": {
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/location-physical-type",
      "code": "ro",
      "display": "Room"
    }]
  },
  "managingOrganization": {
    "reference": "Organization/benhvien-a"
  }
}

5. Relationships between administrative Resources

┌──────────────────┐
│   Organization   │ ← Bệnh viện/Phòng khám
│   (benhvien-a)   │
└───────┬──────────┘
        │ managingOrganization
        ▼
┌──────────────────┐        ┌──────────────────────┐
│    Location      │◄───────│   PractitionerRole   │
│ (phong-kham-tm)  │        │  (dr-tran-role-bva)  │
└──────────────────┘        └───────┬──────────────┘
                                    │ practitioner
                                    ▼
                            ┌──────────────────┐
                            │  Practitioner    │
                            │  (dr-tran-001)   │
                            └──────────────────┘
                                    ▲ generalPractitioner
                                    │
                            ┌──────────────────┐
                            │    Patient       │
                            │ (vn-patient-001) │
                            └──────────────────┘

6. Practice: Create a complete Resources system

Let's create a practical workflow: patient registration at the hospital.

Step 1: Create Organization

curl -X POST http://localhost:8080/fhir/Organization \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Organization","name":"Bệnh viện Đa khoa A","active":true}'
# Ghi lại id trả về → {org-id}

Step 2: Create Practitioner

curl -X POST http://localhost:8080/fhir/Practitioner \
  -H "Content-Type: application/fhir+json" \
  -d '{"resourceType":"Practitioner","name":[{"family":"Trần","given":["Minh","Đức"],"prefix":["BS"]}],"active":true}'
# Ghi lại id trả về → {prac-id}

Step 3: Create Patient associated with Organization and Practitioner

curl -X POST http://localhost:8080/fhir/Patient \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "resourceType": "Patient",
    "name": [{"family":"Nguyễn","given":["Thị","Mai"]}],
    "gender": "female",
    "birthDate": "1992-08-10",
    "generalPractitioner": [{"reference":"Practitioner/{prac-id}"}],
    "managingOrganization": {"reference":"Organization/{org-id}"}
  }'

Step 4: Verify — Search for Patients with _include

# Tìm patient kèm thông tin Practitioner
curl -s "http://localhost:8080/fhir/Patient?_include=Patient:general-practitioner" | jq '.entry[].resource.resourceType'
# Kết quả: "Patient", "Practitioner"

7. Summary

Patient: data center, contains identifiers, demographics, contacts
Practitioner: personal information of medical staff, degrees, certificates
PractitionerRole: specific role at a specific organization (1 person in many roles)
Organization: hospital, clinic, department, department
Location: physical location (room, floor, bed)
Resources are linked together References
Use Identifiers suitable for the Vietnamese context (CCCD, health insurance, MRN)

Lesson 4: Patient, Practitioner, Organization - Administrative Resources