Skip to content

The d2w fhir series

d2w fhir turns a DHIS2 instance's metadata into a FHIR Implementation Guide source tree: a SUSHI project whose FSH (FHIR Shorthand) definitions and pre-built registry JSON are generated from the DHIS2 API and published as FHIR resources by the IG publisher. One plugin covers the whole loop: init scaffolds a dockerized project, validate grades the instance's codes by build impact, generate writes the IG source, the IG publisher compiles the browsable guide, serve runs the compiled project as a read-and-capture FHIR endpoint, and forward posts what that endpoint captured back into DHIS2. doctor runs that whole chain against one instance and reports what the instance breaks.

Most projects need three things, in this order: a facade running, that facade pointed at a DHIS2 instance, and that facade accepting captures in the format the guide publishes. Introduction is those three steps on one page, with the command that does each and the link that owns it - read it first if you are new here. Everything else in this series is depth behind one of those steps, or one of the capabilities that sit beyond them.

The series is graded 100 to 501: the 100 page is the front door, 101 pages explain and demonstrate, 201 pages operate a project day to day, 301 pages configure fhir.toml, 401 pages integrate against and extend what the project publishes, and 501 pages teach the expression languages that compute over FHIR data. Every page states who it is for; start where your question lives.

Every term either side of the boundary - DHIS2's and FHIR's - has an entry in the Glossary. Read it first if a word in any page below is carrying more meaning than you can place, and keep it open beside the page you are working through.

Where to start

Find the sentence that describes your situation. Each row is a reading order, not a menu - the pages build on each other left to right.

Your situation Read, in this order
You are new here and want the shape of it Introduction, then whichever step you need depth on
You run a DHIS2 instance and want its forms available as FHIR Introduction, What d2w fhir is and why, Quickstart, then the 201 pages from Check an instance with doctor onward
You have to get a facade up on a real instance, reachable and forwarding Run a secured facade on a real instance, following each step's link where you need the depth
You are deciding whether your ministry should publish a guide at all What d2w fhir is and why, then the project-level design records: the FHIR roadmap and review guide, the DHIS2 fidelity audit, and the harmonization design
You integrate a system against a guide someone else published Glossary, FHIR for DHIS2 people, then the 401 pages from The capture contract
You configure what the guide contains Quickstart, Validate the instance, then the 301 pages from The settings file
You operate a project that already exists Check an instance with doctor, then the 201 pages in order
You are new to FHIR entirely Glossary, FHIR for DHIS2 people, What d2w fhir is and why
You want to compute over FHIR data - expressions, logic, quality measures FHIRPath, CQL, Quality measures, then The FHIR version binding

Start here

  • Introduction - what a d2w fhir facade is, the three steps that get you one, and the command that does each. The page to read before any other.

101 - Understand

  • Glossary - every DHIS2 term and what the toolkit does with it, every FHIR and toolkit term and what it is in DHIS2 terms. A dictionary, read by lookup.
  • What d2w fhir is and why - why a ministry publishes an IG, what the verbs produce, what it costs. No commands.
  • FHIR for DHIS2 people - the FHIR model itself, explained in DHIS2 terms and at length. Where the glossary gives you a sentence, this gives you the reasoning.
  • Quickstart: from nothing to a served IG - scaffold, validate, generate, compile, and serve a guide from a DHIS2 instance.

201 - Operate a project

301 - Configure fhir.toml

  • The settings file: fhir.toml - where the file lives, how it is read, and the map of its tables.
  • Who the guide is - profile and the [ig] table: id, canonical, publisher.
  • What goes in - the selection tables: data sets, programs, option sets, categories, organisation units.
  • How things are generated - [generate] and [generate.naming]: the identity stem, concept codes, and the canonical token registry.
  • Serving it - the [serve] table: host, port, spool, capture behaviour, and the register of tracked entities.

401 - Integrate and extend

501 - Evaluate

The expression languages that compute over FHIR data, in the dhis2w-fhir-engine package. Written for someone who knows DHIS2 and has never seen an expression language, and needing no DHIS2 instance, no server, and no generated project - every page runs against data you paste in. The exception is held to the end of each language page: a closing section that runs the same logic against a served project or a seeded instance, and says so.

  • FHIRPath - the smaller language: paths, filters, and functions over one resource or one Bundle, and why every expression answers with a collection.
  • CQL - the bigger language: a named, versioned library, what its header binds, how a retrieve reaches data, how a ValueSet scopes one, and how an interval bounds a reporting period.
  • Quality measures - the populations, the scoring rules, the MeasureReport that comes out, and the DHIS2 payoff: indicators published as computable measures.
  • The FHIR version binding - what is FHIR-version-neutral, what is R4-bound, and what an R5 sibling would provide.

Reference

The design record

The reasoning behind the shapes these pages describe lives under Project, not here. Read them when you want the why rather than the how:

  • FHIR roadmap and review guide - what exists, the settled and open decisions, the review dimensions.
  • FHIR conversion layer - how data crosses the boundary in both directions.
  • Corrections and withdrawals - how a submitted value is corrected or retracted.
  • DHIS2 fidelity audit - every concept that makes DHIS2 distinctively DHIS2, and whether the guide carries it.
  • FHIR harmonization - how several country guides relate.
  • The IPS document - what an International Patient Summary requires, which sections a DHIS2 tracker instance could feed, and the prototype that makes the reserved decisions concrete (examples/fhir/client/ips_document.py).
  • FHIR enrollment resource - why the read side models an enrollment as it does.
  • The library surface - what the FHIR toolchain is apart from its commands: what is importable today, the composition contract the served facade is missing, and the sequence that closes the gap.
  • The materialized projection - what it takes to serve FHIR from a synced backend rather than a live proxy: the measured limits of the live model on population evaluation and multilingual person search, the sync doctrine, and the backends that could hold it.