FHIR Foundations

FHIR is the modern, web-friendly successor to HL7 v2 and CDA. Where v2 used pipe-delimited messages and CDA used dense XML documents, FHIR uses small, composable JSON (or XML) documents called Resources, exchanged over a normal REST API.

The four big ideas

1. Resources — small, focused units like Patient, Observation, MedicationRequest. Each is a self-describing JSON object.
2. References — resources point to each other by URL: an Observation has subject: { reference: "Patient/123" }.
3. REST — GET /Patient/123, POST /Observation, GET /Observation?patient=123&code=8480-6.
4. Profiles — constraints layered on top of base resources to fit a use case (this is what US Core is).

Why it matters

FHIR is now the legally required interoperability standard in the US (ONC Cures Act). Every certified EHR must expose a FHIR R4 API, and the data shape they must expose is defined by US Core.

Every FHIR server exposes resources at the same URL shape:

GET    [base]/Patient/{id}        # read one
GET    [base]/Patient?name=smith  # search
POST   [base]/Patient             # create
PUT    [base]/Patient/{id}        # update (whole resource)
PATCH  [base]/Patient/{id}        # partial update
DELETE [base]/Patient/{id}        # delete

Search has a grammar

Each resource type defines search parameters. Common modifiers:

• name=smith — string match
• birthdate=ge1980-01-01 — comparator prefixes (eq, ne, gt, lt, ge, le)
• code=http://loinc.org|8480-6 — token with system|code
• _include=Observation:patient — pull referenced resources
• _revinclude=Provenance:target — pull resources that reference this one
• _count=50, _sort=-date — paging and ordering

Responses come back as a Bundle of type searchset containing entries.

Base FHIR is deliberately permissive — almost every element on Patient is optional, and codes can come from anywhere. That's good for global flexibility, bad for interoperability inside one country.

A Profile narrows things down by saying:

• which elements are required (cardinality 1..1)
• which elements are Must Support (you must be able to handle them if present)
• which value sets are bound (e.g. race must come from the OMB Race value set)
• what extensions are allowed

A profile is itself a FHIR resource (a StructureDefinition). The instance you send still looks like a regular Patient, but it claims conformance with:

"meta": {
  "profile": ["http://hl7.org/fhir/us/core/StructureDefinition/us-core-patient"]
}

US Core is exactly this: a published set of StructureDefinitions, value sets, and search parameters that every certified US EHR must support.

Every FHIR resource has the same backbone:

• resourceType — what kind of thing this is. Always present, always first by convention.
• id — the server-assigned logical id. Combined with resourceType this forms the reference (Patient/abc).
• meta — bookkeeping: versionId, lastUpdated, and the profile array claiming conformance.
• The rest — fields specific to the resource (name, gender, birthDate for Patient).

Notice the example below: identifier, name, and telecom are arrays, because patients can have several of each. Codes use system + code together — the system tells you the meaning of the code.