fhir-rust — documentation index
Every entry point in the repository, in one place. If you know what you want,
this is the fastest route; if you do not, start with
README.md.
The repository holds four families: the model crate (fhir/), the
persistence core (fhir-store/), the six database ports
(fhir-<engine>/), and the HTTP surface (fhir-loco/). Most
of this page is about the database ports, which are the largest; the other three
have their own sections at the end. spec/index.md is the root of every specification and
says which one governs which code.
By what you are doing#
Evaluating#
| README | what this is, in five minutes |
| Choosing an engine | which of the six, and what each costs |
| Conformance matrix | what each port actually satisfies today |
| The storage model | how a FHIR® resource becomes tables |
| Trust boundary | what is guaranteed, what your deployment must add |
| PHI.md | the same question in plain language, for a privacy or security review |
| FAQ | the questions that come up first |
Building something#
| Tutorial 1 — first store | install a schema, write and read a resource |
| Tutorial 2 — the schema | base tables, child tables, ords, extensions |
| Tutorial 3 — SQL | query the relational schema directly |
| Tutorial 4 — FHIR search | search parameters, modifiers, the fold |
| Tutorial 5 — history and audit | versions, attribution, the hash chain |
| Tutorial 6 — porting | adding a seventh database |
| Examples | short, runnable recipes |
Using an AI agent#
llms.txt · llms.json |
curated map of the repo for AI tools, plain text / structured — spec |
fhir-skill/ |
agent skill: FHIR® concepts, terminology, examples — for end users |
fhir-rust-maintainer-skill/ |
agent skill: checklists and commands for maintaining this repository |
| fhir-rust.github.io/llms.txt | the same map, generated with links that resolve on that domain instead of this repository's paths |
Contributing#
| CONTRIBUTING.md | ways to help, then the five rules and the green gate |
| RFC.md | open questions, and the kind of feedback that helps |
| AGENTS.md | how to work here — start here |
| GOVERNANCE.md | who decides what, recorded where, and how to disagree |
| CODE_OF_CONDUCT.md | conduct, including the claim-accuracy clause |
| SECURITY.md | reporting a vulnerability |
| Topic guides | spec workflow, rust, testing, databases, docs, security, release |
| CLAUDE.md | agent-specific notes and traps |
| Audit findings | what is currently broken, with evidence |
Promoting and outreach#
| Outreach | the channels, the claims register, and the seven assets that gate any of it |
Implementing or auditing#
| Specification root | all four families, precedence, id namespaces |
| Publishing readiness | how all 34 crates reach crates.io — a documented laptop step, by decision |
| Trusted Publishing | why not yet, checked against each forge's actual support rather than assumed |
| Database core | the normative core, sections 0–16 |
| Compliance mapping | regulation → requirement → evidence |
| Conformance matrix | per-port status |
The database specification#
One copy, shared by all six ports. Requirement ids are permanent (C0.5).
| Section | Prefix | Subject | |
|---|---|---|---|
| 0 | Conformance | C0.x |
keywords, id grammar, levels, retired sections |
| 1 | Scope | S1.x |
FHIR versions, resource coverage, engine floors |
| 2 | Schema generation | G2.x |
determinism, identifiers, install |
| 3 | Storage model | M3.x |
tables, types, extensions, audit, hash chain |
| 4 | Shredding and reconstruction | R4.x |
lossless round-trip, snapshot reads |
| 5 | Versioning and history | H5.x |
versions, soft delete, vread |
| 6 | Search | P6.x |
parameters, folding, indexes, bounded cost |
| 7 | — | — | retired: REST API |
| 8 | — | — | retired: CLI |
| 9 | Validation | V9.x |
structural, strict, terminology gap |
| 10 | Operations | O10.x |
logging, migrations, TLS, supply chain |
| 11 | Conformance testing | T11.x |
what must be tested, and how honestly |
| 12 | Trust, principal, audit | PR12.x |
attribution, disclosure logging |
| 13 | Compliance mapping | — | HIPAA, GDPR, ONC, IEC 62304 |
| 14 | per port | M14.x |
that engine's departures |
| 15 | Portability and dialects | X15.x |
what is shared, what an annex must say |
| 16 | Repository and release | W16.x |
layout, SSOT, versioning |
| — | Locale and accent folding | L1–L16 |
the fold, normatively |
| — | Search adjuncts | U1–U13 |
bounded and checksum adjuncts for any unindexable search target |
Non-normative companions: conformance matrix · audit findings.
R4.x is the one prefix this specification shares with the model crate's, where
it means something unrelated. spec/index.md
has the disambiguation rule.
The ports#
Each has its own index, dialect annex, book, and work breakdown.
| Port | Spec | Guide | Book | Plan | Tasks |
|---|---|---|---|---|---|
fhir-postgresql |
spec · annex | AGENTS | book | plan | tasks |
fhir-sqlite |
spec · annex | AGENTS | book | plan | tasks |
fhir-mysql |
spec · annex | AGENTS | book | plan | tasks |
fhir-mariadb |
spec · annex | AGENTS | book | plan | tasks |
fhir-mssql |
spec · annex | AGENTS | book | plan | tasks |
fhir-oracle |
spec · annex | AGENTS | book | plan | tasks |
All six annexes are now real — the MSSQL and Oracle ones were the MySQL annex
with three lines changed until 2026-07-31, and both were rewritten from the
X15.6 checklist (audit.md F-16). All six are still
marked proposed (X15.9), so none may be cited as evidence for a conformance
level yet.
The model crate#
fhir/ — the FHIR data model and the generator that produces it from
the official specification JSON. No database, no I/O; the database ports do not
depend on it.
| README | what it is, and how to depend on it |
| Specification | 14 sections, ids R1.x–R14.x |
| Assurance | what must hold before it is trusted clinically |
| Cross-release conversion | moving a resource between releases, and what that costs |
| AGENTS · topic guides | how to work in it |
| CHANGELOG |
Its R4.x ids are not the database specification's R4.x; see
spec/index.md.
The persistence core#
fhir-store/ — the engine-agnostic half of storage: the
tamper-evident audit chain (M3.16), the attribution and disclosure records
(PR12.x), and the value types every port's operations return. No driver, no
socket.
| README | what is in it, and what stays in a port |
| Governed by | spec/databases/ — it is the ports' own core, not a separate spec |
It exists because chain.rs was 618 lines byte-identical in all six ports and
the shared-core gate did not watch it (F-45).
The HTTP surface#
fhir-loco/ — a FHIR RESTful API server (Axum, Loco) over
fhir-sqlite. The database ports carry no server of their own by design
(C0.17), and this is where that surface lives.
| README | endpoints, running it, what belongs where |
| plan | its design decisions, and the open ones ($export) |
| tasks | its work breakdown |
| Specification | fhir-loco/spec/index.md — 4 sections, ids SV1.x–SV4.x |
Reading order, if you have an hour#
- README — 5 min
- Storage model — 15 min, the one idea everything rests on
- Tutorial 1 — 15 min, hands on
- Conformance matrix — 10 min, what is actually true
- Audit findings — 15 min, what is not
Trademarks#
HL7®, and FHIR® are the registered trademarks of Health Level Seven International and their use of these trademarks does not constitute an endorsement by HL7.