build

Builder's field guide: the FHIR ecosystem in one map

Updated — · Level 2

The FHIR world looks sprawling until you see that it's five things. Here's the map, with the doors we actually use.

1. The spec and its IGs. The base spec (hl7.org/fhir) defines resources; Implementation Guides profile them for a job. Our stack: US Core (the US profile floor), HRex (the Da Vinci trunk everything shares), then CRD/DTR/PAS (prior auth), PDex + CARIN Blue Button (payer data out). Reading order for any IG: Home → Actors/Use cases → Profiles → Examples. Anything at build.fhir.org is the CI build — a moving draft; published versions live under hl7.org/fhir/... with a version directory.

2. Packages — how versions actually work. Every IG ships as an npm-style package (hl7.fhir.us.davinci-pas#2.1.0). The registry (registry.fhir.org, API at packages.simplifier.net) is searchable and free; every IG also publishes a package-list.json listing all its versions and their status (ballot, trial-use, normative, withdrawn). That file is how our IG catalog knows when we're validating against yesterday's version.

3. Validation. The official validator (same engine inside HAPI and our workbench) checks payloads against packages. Rule of thumb: validate against the exact package versions your partner declared — cross-version errors waste days. Our Validation Workbench exists so you can do this in a browser with the payer's IG stack preloaded.

4. Testing. Inferno (ONC-backed, open source) has test kits for US Core, PAS, DTR, CRD — the closest thing to "will this pass a real conformance review." Synthea generates synthetic patient bundles when you need volume. Our Washer (planned) covers the third case: test data that must keep the shape of your production payloads.

5. The community. chat.fhir.org (Zulip) is where the IG authors answer questions, usually same-day: #implementers for general, per-IG streams for Da Vinci work, #tooling for validator weirdness, #hapi for our sidecar server. Public read without an account; free account to post. Search before asking — your error message has usually been posted before. Connectathons (HL7-run, several per year) are where implementations get tested against each other; Da Vinci tracks are the ones to watch for our niche.

The habit that ties it together: when something confuses you, resolve it in this order — the IG's own pages → the package versions → chat.fhir.org search → ask in the narrowest stream. That path answers nearly everything faster than any vendor doc.

Go to the source