Write an IG site’s static terminology index from the IG’s own cache

Read the IG Publisher’s expansions.json and txcache/, as ig-cache.sh restore leaves them, and write index.json (gzipped as index.json.gz over 1 MB): every code with its system and display, and each value set’s codes. The IG site’s service worker answers the self-hosted Form Builder’s LOINC search from it, and its UCUM search from the vendored full UCUM list, so the site makes no cross-site call. build-ig-site runs it for every IG with a Questionnaire.

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, fhir-core, 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, 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
inexpansionsFilesystemPathoutput-ast/expansions.json.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
intxcacheFilesystemPathinput-cache/txcache/.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inoutFilesystemPathyesWhere index.json (or index.json.gz) is written.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
outindexFilesystemPathThe index file, and a count of codes and value sets on stdout.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.

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/terminology-index.ts --expansions <expansions> --txcache <txcache> --out <out>.
  • 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
networkno
when to choose it
whenBuilding an IG site whose Questionnaires are edited in the self-hosted Form Builder, or whose form views need answerValueSet expanded without a terminology server.
limitsOnly what the IG’s own Publisher run looked up: a LOINC code the IG never used is not in it, and the site says so (“not in this IG’s terminology cache; add it via the FSH source”) rather than asking a server. A cache entry that does not parse is skipped.
costReads the cache once; seconds.

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/terminology-index.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/terminology-index.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "terminology-index",
  "title": "Write an IG site's static terminology index from the IG's own cache",
  "description": "Read the IG Publisher's `expansions.json` and `txcache/`, as `ig-cache.sh restore` leaves them, and write `index.json` (gzipped as `index.json.gz` over 1 MB): every code with its system and display, and each value set's codes. The IG site's service worker answers the self-hosted Form Builder's LOINC search from it, and its UCUM search from the vendored full UCUM list, so the site makes no cross-site call. `build-ig-site` runs it for every IG with a Questionnaire.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/terminology-index.ts --expansions <expansions> --txcache <txcache> --out <out>"
  },
  "io": {
    "inputs": [
      {
        "name": "expansions",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "`output-ast/expansions.json`.",
        "required": false
      },
      {
        "name": "txcache",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "`input-cache/txcache/`.",
        "required": false
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "Where `index.json` (or `index.json.gz`) is written.",
        "required": true
      }
    ],
    "outputs": [
      {
        "name": "index",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "The index file, and a count of codes and value sets on stdout."
      }
    ]
  },
  "satisfies": [
    "ig-build-pipeline"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "Building an IG site whose Questionnaires are edited in the self-hosted Form Builder, or whose form views need `answerValueSet` expanded without a terminology server.",
    "limits": "Only what the IG's own Publisher run looked up: a LOINC code the IG never used is not in it, and the site says so (\"not in this IG's terminology cache; add it via the FSH source\") rather than asking a server. A cache entry that does not parse is skipped.",
    "cost": "Reads the cache once; seconds."
  }
}

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