Authoring a WHO SMART IG (L3)

On this page
  1. Prerequisites
  2. The L3 pipeline
  3. Workflow
  4. Making the build incremental
  5. A mock session
  6. Next

This page is generated from site-docs/source/guides-who-smart-ig/ — each section below links to its own source.

✎ Edit

The L3 layer turns an L2 DAK into a computable FHIR Implementation Guide. This guide covers authoring FHIR artifacts as FSH, compiling with SUSHI, validating, and publishing with the HL7 IG Publisher — all driven by the LLM.

Skill package: authoring-who-smart-guidelines

Prerequisites

✎ Edit

The L3 toolchain is heavier than the platform baseline. The authoring-who-smart-guidelines package’s Docker manifest provisions it; to run locally you need:

ToolPurposeInstall
Java 21 (JRE)IG Publisherapt install openjdk-21-jre-headless
FHIR IG Publisherbuild the IGdownload publisher.jar from HL7/fhir-ig-publisher
SUSHI (fsh-sushi)compile FSH → FHIRnpm i -g fsh-sushi
JekyllIG site renderinggem install jekyll bundler

Run bun run cat check-deps and the agent’s check_dependencies tool to confirm.

The L3 pipeline

✎ Edit

BPMN swimlane diagram: the FHIR modeller maps L2 to L3 and authors FSH, the build pipeline compiles with SUSHI and validates against profiles, a failed validation returns to FSH authoring, the QC reviewer's gates file findings as beans when they fail, and a clean run goes through the IG Publisher to a published IG site.

BPMN 2.0 source · full-size SVG

StepSkill
Author FSH (profiles, extensions, value sets, examples)l3-fhir-authoring
Validate against FHIR profilesfhir-validation
QC gatesquality-control
Publish the IGig-publication

Workflow

✎ Edit

  1. Map L2 → L3 — l3-fhir-authoring: turn each data element into a FHIR profile, each value set into a ValueSet, each decision into a PlanDefinition / Library as appropriate.
  2. Author FSH — the agent writes FHIR Shorthand; SUSHI compiles it to FHIR resources.
  3. Validate — fhir-validation runs the validator against the profiles.
  4. QC — quality-control enforces the IG’s quality gates.
  5. Publish — ig-publication runs the IG Publisher and renders the site.

Making the build incremental

✎ Edit

BPMN swimlane diagram: a source change restores the derived state; if the cache is usable the build computes the change's dependency cone, posts the cone report for the reviewer, checks out and compiles only the cone, validates it against the warm validator service, re-renders the cone's records, merges them with the restored ones, rebuilds the meta-index and assembles the site; a cache miss or a moved toolchain falls back to a full publisher build; QC gates run on the aggregate QA and file findings as beans; a PR branch deploys a preview and never seeds, while main or a release deploys the site and seeds the cache from the green build.

BPMN 2.0 source · full-size SVG

Every trigger in a DAK repository — a push to a PR branch, /validate, /deploy, a push to main, a release — runs the same full IG Publisher build, and a one-line edit to one profile costs all of it. Proposal: incremental IG build measures why that is avoidable: on the immunizations IG the median artefact has no dependents and the 90th percentile has six, so almost every edit invalidates a handful of resources and the index. Its overview lists the eleven changes and pins each to the stage of the review and publish pipeline where it runs.

The process above is the L3 pipeline’s build lane once the derived artefacts are cached by dependency cone. Restore first; compute the change’s cone with bun run content/pipeline/fsh-cone.ts <ig-root> --changed <files>; compile and validate only the cone against the warm validator; re-render the cone’s records; rebuild the meta-index; assemble the site. A cache miss or a moved toolchain falls back to today’s full build, and only a green build of main or a release seeds the cache.

StepImplemented by
Restore and seed the derived stateig-cache.sh (proposed; the lake-cache.sh contract)
Compute the cone of the changecontent/pipeline/fsh-cone.ts
Validate the conefhir-validation over the warm validator service (proposed MCP tools)
Rebuild the meta-index, assemble the siteig_metaindex_rebuild (proposed), ig-publication
QC gates, deployquality-control, content-publish

A mock session

✎ Edit

You: Generate the FHIR profile and value set for the immunization data dictionary from the L2 DAK, then build the IG.

Assistant: (loads l3-fhir-authoring) Authored ImmunizationRecord profile + AntigenCodes value set as FSH. (runs SUSHI) Compiled to FHIR R4. (loads fhir-validation) Validator: 0 errors, 2 warnings. (loads ig-publication) Built the IG with the HL7 publisher — site is in output/.

You: Show me the QA report.

Assistant: (loads quality-control) QA: broken links 0, profile conformance ✓, terminology bindings resolved ✓.

Next

✎ Edit

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed b08c961 · 2026-10-23T23:11:09Z