FHIR Primer

This is a condensed overview. For the full specification, see hl7.org/fhir.

What is FHIR?

FHIR (Fast Healthcare Interoperability Resources) is a standard for representing healthcare data as resources and exchanging them over HTTP via a REST API.

Resources

A resource is a structured document with a known shape. FHIR defines several formats (JSON, XML, RDF). Ferrum supports JSON and XML; this documentation uses JSON for examples. It might represent a person (Patient), an event (Encounter), or a clinical fact (Observation). Every resource has a resourceType, and most include an id and meta:

{
  "resourceType": "Patient",
  "id": "example",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2025-01-15T10:30:00Z"
  },
  "name": [{ "family": "Doe", "given": ["Jane"] }],
  "birthDate": "1990-03-15"
}

Three “infrastructure” resources appear constantly:

Bundle — groups multiple resources (search results, batches, transactions)
OperationOutcome — error and validation messages
CapabilityStatement — a server’s self-description (GET /metadata)

REST API

FHIR uses standard HTTP methods:

Operation	Method	URL pattern
Create	`POST`	`/fhir/{type}`
Read	`GET`	`/fhir/{type}/{id}`
Update	`PUT`	`/fhir/{type}/{id}`
Patch	`PATCH`	`/fhir/{type}/{id}`
Delete	`DELETE`	`/fhir/{type}/{id}`
Search	`GET`	`/fhir/{type}?param=value`

Search

Search returns a Bundle of type searchset. Parameters are typed — the same parameter name behaves differently depending on its type:

Type	Example
string	`name=Doe` (prefix match)
token	`code=http://loinc.org\|29463-7`
date	`birthdate=ge2000-01-01`
reference	`subject=Patient/123`
quantity	`value-quantity=gt5.0\|\|mg`

Common result parameters: _count, _sort, _include, _revinclude, _summary, _elements.

Terminology

FHIR uses coded values extensively:

CodeSystem — defines a set of codes (LOINC, SNOMED CT, ICD-10, …)
ValueSet — a curated subset of codes allowed in a given context
Coding — one code from one system (system + code)
CodeableConcept — one or more Codings plus optional human-readable text

Servers expose terminology operations like $expand, $lookup, and $validate-code.

Profiles and Extensions

Profiles (StructureDefinitions) constrain base resources for specific use cases — restricting cardinality, fixing values, or adding required elements. Extensions let you add data that isn’t in the base model, identified by a canonical URL.

Key Concepts at a Glance

Term	Meaning
Bundle	Container for multiple resources
Compartment	Scoped view of resources related to an instance (e.g. `Patient/123/Observation`)
ETag / If-Match	Version-aware concurrency control
FHIRPath	Expression language for navigating resources
Operation	`$`-prefixed procedure beyond CRUD (e.g. `$expand`, `$validate`)
Transaction	Atomic batch — all entries succeed or all fail

Getting Started

Server

What is FHIR?

Resources

REST API

Search

Terminology

Profiles and Extensions

Key Concepts at a Glance

Further Reading

​What is FHIR?

​Resources

​REST API

​Search

​Terminology

​Profiles and Extensions

​Key Concepts at a Glance

​Further Reading

What is FHIR?

Resources

REST API

Search

Terminology

Profiles and Extensions

Key Concepts at a Glance

Further Reading