Skip to main content
Spec references: https://hl7.org/fhir/resourcelist.html, https://hl7.org/fhir/resource.html, https://hl7.org/fhir/datatypes.html

​
What a resource is (practically)

A FHIR resource is a JSON document with a known shape. It might represent a person (Patient), an event (Encounter), or a clinical fact (Observation). Every resource has a resourceType, and most resources you read from a server will also include an id and meta. Some “infrastructure” resources show up constantly too: Bundle (search results), OperationOutcome (errors/validation), and CapabilityStatement (/metadata).

​
Anatomy of a resource

Most resources share the same “envelope”, plus fields that are specific to that resource type. 
{
  "resourceType": "Patient",
  "id": "example",
  "meta": { "versionId": "1", "lastUpdated": "2026-01-01T12:34:56Z" },
  "text": { "status": "generated", "div": "<div>...</div>" }
}
Common top-level fields:
  • resourceType (required) — the type of the resource (Patient, Observation, …)
  • id — the logical id used in URLs (/fhir/{resourceType}/{id})
  • meta — server-managed metadata (e.g. versionId, lastUpdated, tags, profiles)
  • text — human-readable narrative (often present, not always)
  • extension / modifierExtension — add fields beyond the base spec (with strict rules)
  • contained — inline resources without their own URL identity (referenced as #id)

​
URLs and content types

FHIR REST endpoints are prefixed with /fhir (for TLQ’s local dev setup, that’s http://localhost:8080/fhir).
  • URLs and IDs are case-sensitive (/Patient/123 ≠ /patient/123)
  • Use Accept: application/fhir+json for JSON responses
  • When sending JSON, also set Content-Type: application/fhir+json
  • Trailing slashes may be accepted (TLQ supports both /Patient and /Patient/)

​
IDs vs identifiers (common pitfall)

Two different concepts show up in many resources:
  • id — the server’s logical id, used in URLs
  • identifier[] — business identifiers (MRN, external ids, etc.), not used in the URL
If you want to find a resource by a business identifier, you typically search instead of constructing a read URL: 
GET /fhir/Patient?identifier=http://hospital.example/mrn|12345

​
References connect resources

References are just another datatype (Reference) that points to a different resource. 
{ "reference": "Patient/123", "display": "Jane Doe" }
You’ll see references in many places (e.g. Observation.subject).

​
Datatypes (a quick mental model)

FHIR fields aren’t “just JSON”; they have defined types (“datatypes”).
  • Primitives: boolean, string, date, dateTime, code, …
  • Complex types: HumanName, Identifier, Address, CodeableConcept, Quantity, Reference, …
When you look at a resource, nested objects are often complex datatypes, and arrays are very common (name[], identifier[], telecom[], …). If something looks unfamiliar, the datatype list is the best place to start: https://hl7.org/fhir/datatypes.html.

​
Try it

1

Read one resource

curl -H "Accept: application/fhir+json" \
  "http://localhost:8080/fhir/Patient/example"
2

Scan for the basics

In the response, find:
  • resourceType
  • id
  • meta.versionId
  • meta.lastUpdated
3

Spot references

References look like this:
{ "reference": "Patient/123" }
They’re how resources connect to each other (e.g. an Observation.subject).
4

Notice datatypes and arrays

Skim a few fields and note the “shape”:
  • Arrays like name[] or identifier[]
  • Nested datatypes like name[0] (HumanName) or identifier[0] (Identifier)

​
Next

CRUD

Create, read, update, patch, delete

Search

Query resources and understand parameters

API Reference

Concrete endpoints and examples

CapabilityStatement

Discover what a server supports