FHIR IN A DAY

3.1

US Core Patient — line by line

Patient is the anchor of every clinical workflow. US Core requires identifier, name, gender, and Must-Supports race, ethnicity, birth sex, and more.

Patient is the subject reference for almost every other resource. Get this one right and the rest of US Core falls into place.

Required (min: 1)

identifier — at least one. Each identifier carries a system (the namespace, e.g. an MRN URL) and a value. Many real Patients have several: MRN, SSN, driver's license, payer member ID.
name — at least one HumanName with family or given.
gender — administrative gender: male | female | other | unknown. This is not clinical sex or gender identity.

Must Support

birthDate, telecom, address, communication.language
Race, Ethnicity, Birth Sex, Gender Identity (all extensions — see next lesson)
Previous Name, Suffix

The "two names" pattern

US Core supports a current legal name and previous names. Use name.use:

official — the legal name
usual — what they go by
old — a previous name (with period.end set)

Example · US Core Patient with race & ethnicity extensions

json

{
  "resourceType": "Patient",
  "id": "amy-shaw",
  "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",
      "system": "http://hospital.example.org/mrn",
      "value": "1032702"
    }
  ],
  "name": [
    {
      "use": "official",
      "family": "Shaw",
      "given": [
        "Amy",
        "V."
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "555-555-1212",
      "use": "home"
    }
  ],
  "gender": "female",
  "birthDate": "1987-02-20",
  "address": [
    {
      "line": [
        "49 Meadow St"
      ],
      "city": "Mounds",
      "state": "OK",
      "postalCode": "74047",
      "country": "US"
    }
  ],
  "communication": [
    {
      "language": {
        "coding": [
          {
            "system": "urn:ietf:bcp:47",
            "code": "en",
            "display": "English"
          }
        ]
      }
    }
  ]
}

3.2

Race, Ethnicity, Birth Sex & Gender Identity

These four extensions are the most distinctive thing about US Core Patient. Each follows a slightly different shape — learn the pattern.

Base FHIR Patient does not natively model race, ethnicity, or birth sex. US Core adds them as extensions with strict bindings to the OMB and HL7 value sets.

Race & Ethnicity (complex extensions)

They are *complex* extensions — extensions containing nested extensions:

ombCategory — 0..5 OMB categories (e.g. White, Black or African American)
detailed — 0..* CDC detailed race codes
text — 1..1 free-text rendering (this is the only required sub-extension)

Birth Sex (simple extension)

Single-valued: valueCode of F | M | UNK | ASKU. This is the patient's sex assigned at birth, distinct from gender.

Gender Identity (US Core 6+)

valueCodeableConcept from a small value set (male, female, non-binary, transgender male/female, other, non-disclose).

Pronouns & Sex for Clinical Use

US Core 7+ added Pronouns and Sex Parameter for Clinical Use (SPCU) — important for accurate ranges (e.g. lab reference intervals).

3.3

Practitioner, PractitionerRole, Organization, Location

Who delivered the care, in what role, at which organization, in which physical place. PractitionerRole is the join.

Real care is delivered by *people in roles at organizations*, not bare practitioners.

Practitioner — the person. Stable across jobs. NPI lives in identifier with system http://hl7.org/fhir/sid/us-npi.
Organization — hospital, clinic, payer, lab. NPI uses the same system as Practitioner.
Location — physical place (room, building, mobile unit). References Organization.
PractitionerRole — the join between a Practitioner and an Organization, with specialty, telecom, and which Locations they work at.

Reference flow

text

Encounter.participant.individual --> PractitionerRole
PractitionerRole.practitioner    --> Practitioner
PractitionerRole.organization    --> Organization
PractitionerRole.location        --> Location

When you write apps that show "Dr. Smith at General Hospital, Cardiology", you are reading PractitionerRole, not Practitioner alone.

Example · Practitioner with NPI

json

{
  "resourceType": "Practitioner",
  "id": "practitioner-1",
  "meta": {
    "profile": [
      "http://hl7.org/fhir/us/core/StructureDefinition/us-core-practitioner"
    ]
  },
  "identifier": [
    {
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "9941339108"
    }
  ],
  "name": [
    {
      "family": "Bone",
      "given": [
        "Ronald"
      ],
      "prefix": [
        "Dr"
      ]
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "555-555-1212",
      "use": "work"
    }
  ]
}

3.4

RelatedPerson — family, friends, surrogates

RelatedPerson is anyone non-clinical involved in the patient's care: parent, spouse, guardian, emergency contact.

RelatedPerson is not another Patient. They aren't the subject of care, they're *related* to one.

Required: patient (the link back) and either name or telecom. Must Support relationship bound to a small role code (MTH, FTH, SPS, GUARD, etc.).

Use cases: emergency contacts, parents on a pediatric chart, designated proxies for SMART app authorization, organ donor next of kin.

Identity & Demographics