FHIR content
On this page
This page is generated from docs/source/fhir-fhir-content/ — each section below links to its own source.
A FHIR Implementation Guide is a published, versioned package of profiles, terminology, examples and prose that says how FHIR is to be used for one purpose. In this knowledge graph it is content of a particular shape, and the shape is what this page is about.
Two things distinguish it from the other content kinds here. It is compiled — an author writes FHIR Shorthand and a tool produces the resources, so the thing an author edits and the thing a reader fetches are different artefacts. And it is published at canonical URLs that other IGs resolve against, so its identity is a URL and a version rather than a path in a repository.
Both have consequences that catch people out, and each is a section below.
L1–L5 — five layers, not five stages; FHIR content is the first three
WHO SMART Guidelines names five knowledge layers. FHIR content lives in the first three, and those three are the clearest available vocabulary for FHIR content generally:
| layer | what it holds | form |
|---|---|---|
| L1 Narrative | narrative guidance — the publication a recommendation comes from | prose, figures, tables |
| L2 Operational | the Digital Adaptation Kit — its ten components, from health interventions to test scenarios | BPMN, DMN, structured tables |
| L3 Machine readable | the FHIR Implementation Guide | FSH → FHIR resources |
| L4 Executable | reference applications and services that execute the static algorithms | software |
| L5 Dynamic | dynamic algorithms trained and optimised on data — the precision-health model | models, analytics |
The five names and their one-line meanings are the WHO Digital
transformation handbook for primary health care (2024), §1.2 pp. 20–21,
ingested as the DAK layer’s library/9789240093362-eng. It cites, as its ref. 18,
the primary source: Mehl G. et al., WHO SMART guidelines: optimising
country-level use of guideline recommendations in the digital age, Lancet
Digital Health 2021;3(4):e213–e216, ingested as
the DAK layer’s library/mehl-2021-who-smart-guidelines (CC BY 3.0 IGO). It
presents the same five as “knowledge layers (L1–L5)”.
This page stops at L3 on purpose. L4 and L5 are software and trained models. They consume what L1–L3 publish, but they are not authored as FHIR content, so nothing in this platform validates them as content. An earlier version of this page said SMART Guidelines “names three layers”. That is the kind of rounding that tells a reader L4 and L5 do not exist.
They are layers, not stages, and the difference is load-bearing. A stage
model says each is produced from the one before and then left behind. In
practice all three are live at once: an L2 decision table and the L3
PlanDefinition derived from it both exist, both are published, and both can
change. Treating L2 as scaffolding that L3 replaces is how a decision table
and its FHIR representation drift apart with nothing to notice.
It is also why an instance may hold any one of the three without the others. An L1 corpus with no DAK behind it is a real thing; so is an IG with no L1.
The SMART layers are not the platform’s layers. cat-harness,
the content core and the science layer are layers of this software.
Each depends on the one before and inherits its skills and directories. L1–L5
are layers of guideline knowledge. A WHO folio holds L1–L3 content; the
platform layers are the tools that author and check it, and none of them is
“the L2 layer”. The deck that set the two side by side is
cat-harness/library/kg-folio-asst-2026-09-30 (slide 1).
Representations, and why only one is taken
The IG Publisher emits three serialisations of every resource — JSON, XML and Turtle — plus HTML per resource page.
This platform’s render path takes the JSON, wrapped in JSON-LD and JSON Schema. That is a decision rather than an omission: three serialisations of one resource are three chances to disagree about what the resource says, and the JSON-LD wrapper carries the semantics the other two were being kept for. An instance that genuinely needs RDF gets it by projecting the JSON-LD, not by shipping the Publisher’s Turtle.
A representation that arrives and is not taken is recorded as a refusal. Otherwise “this IG publishes no Turtle” and “we ignored its Turtle” become the same observation, and only one of them is a fact about the IG.
The .html case is different and worth separating. The Publisher’s HTML is
not a serialisation of a resource — it is a rendering, with the Publisher’s
own navigation, theme and cross-links baked in. Mounting it is what this
platform is moving away from, because finished HTML carries no front matter:
the navbar, the language bar, the QA badges and the translation surface all
stop at its edge.
The artefact index is reconstructed
No FHIR IG publishes an index of its own artefacts. This is the fact that shapes every attempt to read one back as a graph, and it surprises people because a published IG plainly knows what it contains.
What exists instead is four partial views, and none is sufficient alone:
| view | carries |
|---|---|
package.tgz → package/.index.json | filename, resourceType, id for every file |
canonicals.json | id, type, url, version, name — canonical resources only |
artifacts.html | the only source of an artefact’s category |
package.manifest.json | package-level metadata |
So an index is reconstructed, and each field records which published file
it came from. The provenance is not bookkeeping: coverage differs per IG, and
badly. canonicals.json covers about a tenth of one WHO IG’s artefacts and
all of another’s. A pipeline that picked a winner on the first IG it met would
be silently wrong on the second, reporting a clean run over the artefacts that
view does not reach.
Two traps are documented because both have been hit:
ValueSets.schema.jsonat the published root is a schema, not an index. It describes an enumeration endpoint’s response and carries anexamplethat holds the list — and the hub page links it to aschemas/directory it is not in.openapi/openapi.jsonis not the DAK API. In at least one WHO IG it is an unrelated domain API, so an ingest that globs for OpenAI-shaped files mis-files it.
The DAK API surface
A WHO SMART Guidelines IG publishes an extra layer on top of standard IG output — the DAK API — produced by scripts that run after the Publisher exits:
<stem>.schema.json— a JSON Schema per logical model and per ValueSet<stem>.displays.json— display labels<stem>.openapi.json— an OpenAPI description<stem>.jsonld— a JSON-LD vocabulary, built from ValueSet expansionsdak-api.html— the hub a reader enters through
Its size varies by two orders of magnitude between IGs, so treat any figure you have seen as a fact about one IG at one version rather than as a property of the surface.
None of this is the Publisher’s work, which is the practical reason to know the boundary: a question about why a schema is missing is a question about a post-processing script, not about the build. And because the JSON-LD vocabularies are built from expansions, they inherit the terminology server’s availability — a thin vocabulary may mean a thin ValueSet or may mean nobody could expand it, and the artefact alone does not say which.
Where the rules live
This page describes the content. The rules are skills, and where the two disagree the skill wins and this page is wrong:
l2-dak-authoringandl3-fhir-authoring— authoring at each layer, and deriving rather than retyping.terminology-management— why terminology has its own lane, and the rule against inventing a code.fhir-validation— the two binaries, and why an absent capability did not pass.ig-artifact-ingestion— reading a published IG back as a graph: which IGs qualify, what to read, what to refuse.ig-render-jekyll— the three contracts for rendering IG content as folio pages, including the JSON-only rule above.smart-stack-layering— which harness layer a given asset belongs to, and the question that settles it.
For the tool that compiles and validates all of this, see The FHIR IG Publisher.