Lesson 11: FHIR Data Types - Primitive, Complex and Special

HL7 FHIR - Basic to Advanced Healthcare Data Standard

Part 4: Data Types, Terminologies and Profiles

xdev.asia

1. Primitive Types

Primitive types are simple, "atomic" values in FHIR.

Type	Description	For example
boolean	true/false	true
integer	32-bit integer	42
integer64	64-bit integer (new R5)	9223372036854775807
string.string	Unicode String (≤ 1MB)	"Nguyen Van A"
decimal	Real numbers (arbitrary precision)	3.14159
uri	URI (RFC 3986)	"http://loinc.org"
url	URL	"https://fhir.example.com"
canonical	URL to conformance resource	"http://hl7.org/fhir/StructureDefinition/Patient"
uuid	UUID (RFC 4122)	"urn:uuid:c757873d-ec9a-4326-a141-556f43239520"
id	Resource ID (1-64 chars, [A-Za-z0-9\-.])	"patient-001"
date. date	Date (YYYY, YYYY-MM, YYYY-MM-DD)	"2025-01-15"
dateTime	Date and time with timezone	"2025-01-15T10:30:00+07:00"
instant. instant	Exact time (xs:dateTime)	"2025-01-15T10:30:00.000Z"
time. time	Hours of the day	"10:30:00"
code	Value from ValueSet	"male"
oid	OID (ISO)	"urn:oid:2.16.840.1.113883.6.1"
markdown	Markdown text	"**Bold** and *italic*"
base64Binary	Base64 encoded	Binary data
positiveInt	Integer > 0	1
unsignedInt	Integer ≥ 0	0

Extensions on Primitive

Even primitives can carry extensions (using the underscore convention):

{
  "birthDate": "1990-05-15",
  "_birthDate": {
    "extension": [
      {
        "url": "http://hl7.org/fhir/StructureDefinition/patient-birthTime",
        "valueDateTime": "1990-05-15T14:30:00+07:00"
      }
    ]
  }
}

2. Complex Types — General-Purpose

Identifier

{
  "use": "official",
  "type": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
        "code": "NI",
        "display": "National unique individual identifier"
      }
    ],
    "text": "CCCD"
  },
  "system": "http://cccd.gov.vn",
  "value": "012345678901",
  "period": {
    "start": "2021-01-01",
    "end": "2036-01-01"
  },
  "assigner": {
    "display": "Bộ Công an"
  }
}

HumanName

{
  "use": "official",
  "text": "Nguyễn Văn A",
  "family": "Nguyễn",
  "given": ["Văn", "A"],
  "prefix": ["BS."],
  "suffix": ["ThS."],
  "period": {
    "start": "1990-05-15"
  }
}

Address

{
  "use": "home",
  "type": "physical",
  "text": "123 Đường Lê Lợi, Phường Bến Nghé, Quận 1, TP.HCM",
  "line": ["123 Đường Lê Lợi"],
  "city": "Hồ Chí Minh",
  "district": "Quận 1",
  "state": "TP.HCM",
  "postalCode": "700000",
  "country": "VN"
}

ContactPoint

[
  {
    "system": "phone",
    "value": "+84901234567",
    "use": "mobile",
    "rank": 1
  },
  {
    "system": "email",
    "value": "[email protected]",
    "use": "home"
  }
]

Coding and CodeableConcept

// Coding — một mã duy nhất
{
  "system": "http://loinc.org",
  "version": "2.77",
  "code": "8480-6",
  "display": "Systolic blood pressure"
}

// CodeableConcept — nhiều Codings + text
{
  "coding": [
    {
      "system": "http://hl7.org/fhir/sid/icd-10",
      "code": "I10",
      "display": "Essential (primary) hypertension"
    },
    {
      "system": "http://snomed.info/sct",
      "code": "38341003",
      "display": "Hypertensive disorder"
    }
  ],
  "text": "Tăng huyết áp nguyên phát"
}

CodeableConcept allows representing the same concept in different CodeSystems — supporting interoperability.

Quantity

{
  "value": 145,
  "comparator": ">=",
  "unit": "mmHg",
  "system": "http://unitsofmeasure.org",
  "code": "mm[Hg]"
}

Period and Timing

// Period
{
  "start": "2025-01-15T08:00:00+07:00",
  "end": "2025-01-15T08:45:00+07:00"
}

// Timing (cho medication dosage)
{
  "repeat": {
    "frequency": 2,
    "period": 1,
    "periodUnit": "d",
    "when": ["ACM", "ACV"],
    "boundsPeriod": {
      "start": "2025-01-15",
      "end": "2025-02-15"
    }
  },
  "code": {
    "text": "Ngày 2 lần, sáng và tối sau ăn"
  }
}

Reference

{
  "reference": "Patient/patient-001",
  "type": "Patient",
  "identifier": {
    "system": "http://hospital.vn/mrn",
    "value": "MRN12345"
  },
  "display": "Nguyễn Văn A"
}

Reference may contain reference. reference (literal URL), identifier (logical reference), or both.

3. Narrative (Human-Readable)

{
  "text": {
    "status": "generated",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p>Bệnh nhân: Nguyễn Văn A, Nam, sinh ngày 15/05/1990</p></div>"
  }
}

Status	Description
generated	Created automatically from structured data
extensions	There is information from extensions that is not in the structured data
additional. additional	There is additional information that is not included in the structured data
empty	No text (empty narrative)

4. BackboneElement

BackboneElement is a complex type only exists inside the resource father, cannot be reused elsewhere. For example: Patient.contact, Encounter.participant, Encounter.diagnosis.

{
  "resourceType": "Patient",
  "contact": [
    {
      "relationship": [
        {
          "coding": [
            {
              "system": "http://terminology.hl7.org/CodeSystem/v2-0131",
              "code": "N",
              "display": "Next-of-Kin"
            }
          ]
        }
      ],
      "name": {
        "text": "Nguyễn Thị B (vợ)"
      },
      "telecom": [
        {
          "system": "phone",
          "value": "+84907654321"
        }
      ]
    }
  ]
}

5. Choice Types [x]

Some elements allow multiple data types — equals symbol [x]:

Element definition	Practical use
value[x]	valueQuantity, valueString, valueCodeableConcept, valueBoolean, ...
onset[x]	onsetDateTime, onsetAge, onsetPeriod, onsetRange, onsetString
effective[x]	effectiveDateTime, effectivePeriod, effectiveInstant, effectiveTiming
deceased[x]	deceasedBoolean, deceasedDateTime
multipleBirth[x]	multipleBirthBoolean, multipleBirthInteger

// Observation value dạng Quantity
{"valueQuantity": {"value": 37.2, "unit": "°C"}}

// Observation value dạng CodeableConcept
{"valueCodeableConcept": {"coding": [{"code": "positive"}]}}

// Observation value dạng string
{"valueString": "Bình thường"}

6. Summary

• Primitive types — 20+ basic types (string, date, code, uri, ...), extensions supported

• Complex types — HumanName, Address, Identifier, CodeableConcept, Quantity, Reference, ...

• CodeableConcept — Most importantly, allow multi-coding for interoperability

• Narrative — Human-readable XHTML in all DomainResources

• BackboneElement — Complex type internal resource

• Choice types [x] — Flexibly choose the appropriate data type