FHIR Patient Resource: HL7 R4 Data Elements, v2-0203 MRN Identifiers, US Core Extensions, and JSON Examples

The FHIR Patient resource (Patient) is the foundational administrative resource in the HL7 Fast Healthcare Interoperability Resources (FHIR) standard used to represent demographic and administrative information about an individual receiving care or participating in a clinical study. In FHIR Release 4 (R4), Patient is a Normative (Maturity Level 5) resource within the Administration module: nearly every clinical, diagnostic, financial, and research resource on a FHIR server—such as Observation, Condition, MedicationRequest, Encounter, and ResearchSubject—references a Patient instance as its subject.

What Data Elements Are in the FHIR Patient Resource?

The HL7 FHIR R4 Patient resource defines 16 core administrative elements covering business identifiers, human names, contact details, demographics, emergency contacts, language preferences, care-team custody, and cross-record identity linkages—deliberately excluding clinical observations or diagnoses.

In the HL7 FHIR resource architecture, clinical facts (such as blood type, smoking status, or problem lists) are never stored directly inside Patient; instead, they are stored as separate Observation or Condition resources that point back to Patient/{id} via subject.reference. The table below lists the normative FHIR R4 Patient data elements, their cardinalities, data types, and clinical informatics rules:

Element	Cardinality	FHIR Data Type	Normative Definition & Terminology Binding
identifier	0..* (1..* in US Core)	Identifier	Business identifiers assigned to the patient (e.g., facility MRN, enterprise EMPI ID, national health ID, or clinical trial participant ID).
active	0..1	boolean	Indicates whether this patient record is in active use (true) or inactivated due to an administrative error or record merge.
name	0..* (1..* in US Core)	HumanName	Structured names with use (usual | official | temp | nickname | anonymous | old | maiden), family, given[], prefix[], and suffix[].
telecom	0..*	ContactPoint	Communication endpoints with system (phone | fax | email | pager | url | sms | other), value, use (home | work | temp | old | mobile), and priority rank.
gender	0..1 (1..1 in US Core)	code	Administrative gender used for record-keeping and bed/billing administration. Required binding to http://hl7.org/fhir/administrative-gender (male | female | other | unknown).
birthDate	0..1	date	Date of birth formatted as YYYY, YYYY-MM, or YYYY-MM-DD. Partial dates are permitted when exact birth dates are unknown or masked for de-identification.
deceased[x]	0..1	boolean | dateTime	Polymorphic choice element serialized in JSON as either deceasedBoolean (true/false) or deceasedDateTime (ISO-8601 death timestamp).
address	0..*	Address	Postal or physical addresses (use, type, line[], city, district, state, postalCode, country, period).
maritalStatus	0..1	CodeableConcept	Most recent marital status bound extensibly to HL7 v3 MaritalStatus (M Married, S Never Married, D Divorced, W Widowed, U Unmarried, UNK Unknown).
multipleBirth[x]	0..1	boolean | integer	Choice element serialized as multipleBirthBoolean or multipleBirthInteger (indicating birth order, such as 1 or 2 for twins in neonatal records).
contact	0..*	BackboneElement	Next-of-kin, emergency contact, legal guardian, or guarantor with relationship[] (bound to v2-0131), name, telecom[], and address.
communication	0..*	BackboneElement	Patient language proficiency containing language (bound to IETF BCP-47 urn:ietf:bcp:47, e.g., en-US, es) and preferred (boolean).
generalPractitioner	0..*	Reference	References to nominated primary care providers (Organization | Practitioner | PractitionerRole).
managingOrganization	0..1	Reference(Organization)	The healthcare organization acting as custodian of this Patient record.
link	0..*	BackboneElement	Cross-references another Patient or RelatedPerson resource representing the same real-world individual using type (replaced-by | replaces | refer | seealso).

How Are Medical Record Numbers (MRNs) Represented in FHIR Patient?

In HL7 FHIR, a Medical Record Number (MRN) is represented as an entry in the Patient.identifier array where identifier.type.coding carries code MR from the HL7 v2 Table 0203 code system (http://terminology.hl7.org/CodeSystem/v2-0203), paired with an organization-specific namespace URI in identifier.system and the identifier string in identifier.value.

Because a patient in an integrated health network or multi-site clinical trial often holds multiple identifiers across facilities, Patient.identifier has 0..* cardinality (`1..*` in US Core). Distinguishing an MRN from a Social Security Number, driver’s license, or Enterprise Master Patient Index (EMPI) identifier requires three sub-elements working together:

1. identifier.type (HL7 v2-0203 Identifier Type): Specifies what kind of identifier is being carried using http://terminology.hl7.org/CodeSystem/v2-0203:
   • MR — Medical Record Number (facility or EHR chart number).
   • PI — Patient Internal Identifier.
   • PT — Patient External Identifier.
   • SS — Social Security Number.
   • DL — Driver’s License Number.
   • AN — Account Number (often mapped from HL7 v2 PID-18 for billing encounters).
2. identifier.system (Assigning Authority Namespace URI): A globally unique URI or OID (such as urn:oid:1.2.840.114350.1.13.861.1.7.5.736980.14 or https://ehr.examplehospital.org/fhir/NamingSystem/mrn) that prevents collisions when two hospitals both assign MRN 104859 to different people.
3. identifier.value (Literal Identifier): The exact string assigned by that namespace, searchable via the token search parameter GET /Patient?identifier=https://ehr.examplehospital.org/fhir/NamingSystem/mrn|104859.

Handling EMPI Merges with Patient.link

When patient registration and EMPI matching workflows detect duplicate charts for the same person, FHIR preserves referential integrity using Patient.link rather than hard-deleting old records:

• The subsumed (deprecated) Patient resource sets "active": false and adds a link entry with "type": "replaced-by" pointing to the surviving Patient resource.
• The surviving Patient resource sets "active": true and includes a reciprocal link entry with "type": "replaces" pointing to the deprecated resource.
• When two separate health systems maintain active records for the same person without merging custody, both records use "type": "seealso".

What Extensions Does US Core Add to the FHIR Patient Resource?

The HL7 US Core Patient Profile (http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient) enforces United States Core Data for Interoperability (USCDI) requirements by making identifier, name, and gender mandatory and adding extensions for OMB race, ethnicity, birth sex, gender identity, and tribal affiliation.

Because the base HL7 FHIR specification is an international standard—and national laws in several European jurisdictions restrict the collection of racial or ethnic categories—race and ethnicity are not core fields on the base Patient resource. For U.S. EHRs certified under ONC 45 CFR § 170.315(g)(10) and mapped from patient registration forms, the US Core Patient Profile defines standard extensions:

• US Core Race Extension (http://hl7.org/fhir/us/core/StructureDefinition/us-core-race): A complex extension containing:
  • ombCategory (0..5, Coding): Bound to the five Office of Management and Budget (OMB) minimum categories in the CDC Race and Ethnicity Code System (urn:oid:2.16.840.1.113883.6.238): American Indian or Alaska Native (1002-5), Asian (2028-9), Black or African American (2054-5), Native Hawaiian or Other Pacific Islander (2076-8), and White (2106-3), plus UNK or ASKU from v3-NullFlavor.
  • detailed (0..*, Coding): Granular CDC race codes (over 900 detailed concepts).
  • text (1..1, string): Human-readable summary of the patient’s race.
• US Core Ethnicity Extension (http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity): A complex extension containing ombCategory (0..1: 2135-2 Hispanic or Latino or 2186-5 Not Hispanic or Latino from urn:oid:2.16.840.1.113883.6.238), detailed (0..*), and text (1..1).
• US Core Birth Sex Extension (http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex): Captures sex assigned at birth via valueCode (F Female, M Male, or UNK Unknown), distinct from administrative Patient.gender.
• USCDI v3 Extensions (US Core 6.1.0+): Adds us-core-sex (sex parameter for clinical use), us-core-genderIdentity, and us-core-tribal-affiliation.

HL7 FHIR Patient Example (JSON) & Java HAPI Model

Below is a complete, schema-valid HL7 FHIR R4 Patient JSON example conforming to the US Core Patient Profile, followed by its programmatic construction using the Java HAPI FHIR reference class org.hl7.fhir.r4.model.Patient:

{
  "resourceType": "Patient",
  "id": "patient-uscore-example-01",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"
    ]
  },
  "extension": [
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-race",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2106-3",
            "display": "White"
          }
        },
        {
          "url": "text",
          "valueString": "White"
        }
      ]
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity",
      "extension": [
        {
          "url": "ombCategory",
          "valueCoding": {
            "system": "urn:oid:2.16.840.1.113883.6.238",
            "code": "2186-5",
            "display": "Not Hispanic or Latino"
          }
        },
        {
          "url": "text",
          "valueString": "Not Hispanic or Latino"
        }
      ]
    },
    {
      "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-birthsex",
      "valueCode": "F"
    }
  ],
  "identifier": [
    {
      "use": "usual",
      "type": {
        "coding": [
          {
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "MR",
            "display": "Medical Record Number"
          }
        ]
      },
      "system": "https://fhir.examplehealth.org/NamingSystem/mrn",
      "value": "MRN-8849201"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Alvarez",
      "given": [" Elena", "Marie"]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "+1-617-555-0148",
      "use": "mobile"
    }
  ],
  "gender": "female",
  "birthDate": "1982-07-14",
  "deceasedBoolean": false,
  "address": [
    {
      "use": "home",
      "line": ["240 Brookline Ave"],
      "city": "Boston",
      "state": "MA",
      "postalCode": "02215",
      "country": "US"
    }
  ],
  "communication": [
    {
      "language": {
        "coding": [
          {
            "system": "urn:ietf:bcp:47",
            "code": "en-US",
            "display": "English (United States)"
          }
        ]
      },
      "preferred": true
    }
  ]
}

Working with org.hl7.fhir.r4.model.Patient in Java (HAPI FHIR)

In Java clinical informatics pipelines and FHIR Bundle builders, the HAPI FHIR structures library (`hapi-fhir-structures-r4`) provides the generated model class org.hl7.fhir.r4.model.Patient:

• Fluent Mutators: Methods such as patient.addIdentifier(), patient.addName(), and patient.addAddress() append new complex elements and return the child object for method chaining.
• Polymorphic Choice Fields: For deceased[x] and multipleBirth[x], org.hl7.fhir.r4.model.Patient exposes setDeceased(new BooleanType(false)) or setDeceased(new DateTimeType("2025-11-02T14:30:00Z")), and hasDeceasedBooleanType() / getDeceasedDateTimeType() for safe type inspection.
• RESTful Operations: A Patient resource supports standard FHIR REST search parameters (_id, identifier, name, family, given, birthdate, gender, telecom, address-postalcode) as well as the $everything extended operation (GET /Patient/[id]/$everything), which returns a searchset Bundle containing the Patient resource together with all compartmental clinical resources linked to that patient.