Refer to HL7’s published FHIR core definitions by canonical URL, and derive their UML class model

Read HL7’s own core package for each stable FHIR release (https://hl7.org/fhir/R4/hl7.fhir.r4.core.tgz, R4B, R5) at the sha1 and sha512 fhir-core/pins.json pins, and keep, under fhir-core/<release>/, only what refers to it or is derived from it: index writes the manifest (each resource, complex, primitive and root type by canonical URL, with HL7’s published JSON for it, its kind, base and the sha256 of its bytes in HL7’s package); uml derives the UML class model HL7 publishes only as pictures, citing the definition and element of every class and attribute; materialise fills a labelled local cache, never committed; check holds all of it to the pins offline; resolve answers with HL7’s URL for a canonical (--cache for the cached copy); diagram prints a type’s Mermaid class diagram. HL7’s publication is the authority: a mirror may only fill the cache. A package that cannot be fetched or verified is recorded as unread with the reason, never as an empty graph.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

ig-build-pipeline

The bare FHIR IG pipeline — FSH to SUSHI to the IG Publisher to a pages branch, with no pre-processing and no post-processing. What this layer runs, what it emits, and the list of things it deliberately refuses to know about. Owns the AST cache lifecycle: an IG site is built from the AST on its cache branch, the publish refuses a stale one, and the reusable ig-ast-refresh.yml is the one writer. Owns what an IG reader may read: contentTypes.ig.include in the repository’s index.config.json, and the legacy warning for a repository that declares none. Read before adding anything to fhir-harness, before onboarding, converting or changing the workflows of an IG repository, and before publishing an IG site.

Source: fhir-harness/skills/fhir-ig-base/ig-build-pipeline.md.

Also satisfied by: build-ig-site, ig-artifact-jsonld, ig-ast-refresh, ig-index-build, ig-page-render-qa, ig-pages, ig-publisher-i18n, ig-repo-site, ig-site-data, ingest-ig-menu, jsonld-vocabularies, logical-model-schemas, stage-ig-sites, strip-library-binaries, strip-library-content, terminology-index, valueset-schemas.

The skill declares no I/O contract (schemas/skills/ig-build-pipeline/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inrootRepoPathThe fhir-harness layer root. Default: the layer this script is in.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inreleaseSlugOne release (R4, R4B or R5). Default: every pinned release (R4 for resolve and diagram).string · pattern ^[a-z0-9][a-z0-9-]*$ · A folio slug, e.g. quantum-observable-universe
intgz-dirRepoPathA directory holding an already-downloaded copy of HL7’s package (hl7.fhir.<r>.core.tgz or <name>-<version>.tgz); still hash-checked against the pin.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outdefinitionsCountDefinitions indexed, classes derived or files cached per release; an unread release is named with its reason.integer · A non-negative count — how many of something, or how many to show. Zero is a real answer.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchBuild and publish the site from the ASTSite build (agent, stage-local)ig-build-pipeline
An IG site, built from the AST on its cache branchDispatch AST refreshPublication manager (owner, or the agent the owner delegates to)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsBuild each IG’s artefact indexHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsGenerate each IG instance’s artefact pagesHost docs site build (CI runner)ig-build-pipeline
Each IG, composed into a host docs site and rendered with just-the-docsClone each IG at its recorded commit and stage itHost docs site build (CI runner)ig-build-pipeline

How it is deployed and reached

  • Command line. From the repository root: bun run fhir-harness/scripts/fhir-core.ts <index|uml|materialise|check|resolve <url>|diagram <Type>>.
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkyes

When a host it reaches is refused:

host / errorremedy
hl7.orgnone: Pass --tgz-dir with HL7’s package fetched elsewhere: the bytes are still checked against HL7’s hashes. Without it, index writes the release unread and uml cannot determine the class model; materialise may still fill the cache from a pinned mirror, file by file against the manifest.
when to choose it
whenBefore a reader resolves a FHIR core type by canonical URL or draws a class diagram of core types (an IG’s logical models or profiles over them), or when a pin changes.
limitsStable releases only. Constraint profiles, extension definitions and logical models in the core package are left out and counted. The class model copies no constraint, binding or description: the cited HL7 definition holds them.
costOne 4-17 MB download per release from hl7.org, then seconds; check, resolve and diagram are offline.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/fhir-core.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.context.jsonld",
  "@id": "https://litlfred.github.io/folio-assistant/fhir-harness/tools/fhir-core.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "fhir-core",
  "title": "Refer to HL7's published FHIR core definitions by canonical URL, and derive their UML class model",
  "description": "Read HL7's own core package for each stable FHIR release (`https://hl7.org/fhir/R4/hl7.fhir.r4.core.tgz`, R4B, R5) at the sha1 and sha512 `fhir-core/pins.json` pins, and keep, under `fhir-core/<release>/`, only what refers to it or is derived from it: `index` writes the manifest (each resource, complex, primitive and root type by canonical URL, with HL7's published JSON for it, its kind, base and the sha256 of its bytes in HL7's package); `uml` derives the UML class model HL7 publishes only as pictures, citing the definition and element of every class and attribute; `materialise` fills a labelled local cache, never committed; `check` holds all of it to the pins offline; `resolve` answers with HL7's URL for a canonical (`--cache` for the cached copy); `diagram` prints a type's Mermaid class diagram. HL7's publication is the authority: a mirror may only fill the cache. A package that cannot be fetched or verified is recorded as `unread` with the reason, never as an empty graph.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/fhir-core.ts <index|uml|materialise|check|resolve <url>|diagram <Type>>"
  },
  "io": {
    "inputs": [
      {
        "name": "root",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The fhir-harness layer root. Default: the layer this script is in.",
        "required": false,
        "arg": {
          "flag": "--root"
        }
      },
      {
        "name": "release",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Slug",
        "description": "One release (R4, R4B or R5). Default: every pinned release (R4 for resolve and diagram).",
        "required": false,
        "arg": {
          "flag": "--release"
        }
      },
      {
        "name": "tgz-dir",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "A directory holding an already-downloaded copy of HL7's package (`hl7.fhir.<r>.core.tgz` or `<name>-<version>.tgz`); still hash-checked against the pin.",
        "required": false,
        "arg": {
          "flag": "--tgz-dir"
        }
      }
    ],
    "outputs": [
      {
        "name": "definitions",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
        "description": "Definitions indexed, classes derived or files cached per release; an unread release is named with its reason."
      }
    ]
  },
  "satisfies": [
    "ig-build-pipeline"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": true
  },
  "remedies": [
    {
      "host": "hl7.org",
      "none": "Pass `--tgz-dir` with HL7's package fetched elsewhere: the bytes are still checked against HL7's hashes. Without it, `index` writes the release `unread` and `uml` cannot determine the class model; `materialise` may still fill the cache from a pinned mirror, file by file against the manifest."
    }
  ],
  "selection": {
    "when": "Before a reader resolves a FHIR core type by canonical URL or draws a class diagram of core types (an IG's logical models or profiles over them), or when a pin changes.",
    "limits": "Stable releases only. Constraint profiles, extension definitions and logical models in the core package are left out and counted. The class model copies no constraint, binding or description: the cited HL7 definition holds them.",
    "cost": "One 4-17 MB download per release from hl7.org, then seconds; `check`, `resolve` and `diagram` are offline."
  }
}

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 dev