> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ferrum.thalamiq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# FHIR Primer

> A quick introduction to the FHIR standard — just enough to use Ferrum effectively.

<Info>
  This is a condensed overview. For the full specification, see
  [hl7.org/fhir](https://hl7.org/fhir/).
</Info>

## What is FHIR?

[FHIR](https://hl7.org/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`:

```json theme={null}
{
  "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                                   |

## Further Reading

* [FHIR Specification](https://hl7.org/fhir/) — the authoritative source
* [FHIR Resource List](https://hl7.org/fhir/resourcelist.html) — all resource types
* [FHIR Search](https://hl7.org/fhir/search.html) — full search documentation
* [FHIR RESTful API](https://hl7.org/fhir/http.html) — HTTP interactions in detail