Write one JSON-LD node per IG artefact, and check a built site’s nodes
write turns an artefact index into artifact/<Type>-<id>.jsonld under a docs root, with no .json twin: one folio-ig-artifact-jsonld/v1 node per artefact, in borrowed vocabularies only (the FHIR RDF class, dcterms, schema.org, PROV), naming the artefact’s canonical URL, its representations and, for a compiled copy, what built it. With --root-resources (the IG site’s default) the first representation is the reduced <Type>-<id>.json the site serves at its root (local), the second the full copy in the AST cache by raw URL (mirror), and each index entry names the root file (schema:contentUrl). check is the kind’s QA: over a BUILT site, every artefact has its node and no node is an orphan, each node is its own file’s, no .json twin is served beside it, and every local resource it names is on the site. It also writes and checks the index node, artifact/index.jsonld (folio-ig-artifact-index-jsonld/v1): every artefact once, each entry naming its node. These are the assets the thin pages render.
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-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.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | command | Text | yes | write or check. | string · A short single-line human string. Not admissible as a command-line argument. |
| in | index | RepoPath | yes | The folio-fhir-artifact-index/v2 to write from, or to check against. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | out | RepoPath | write: the docs root the nodes go under. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | dir | RepoPath | check: the built docs root to check. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | base | Url | write: the docs root’s published URL, for absolute IRIs. | string · format uri · An absolute http(s) URL | |
| in | compiled-data | RepoPath | write: where compiled resource files are served, from the docs root, or the AST cache commit’s raw base (then a mirror). | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | root-resources | Flag | write: the site serves each compiled resource at its root as <Type>-<id>.json; each node lists it first. | boolean · A boolean switch — projects to a bare flag, with no value word | |
| out | nodes | Count | Nodes written, or checked; check exits 1 with each finding named. | 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:
| process | step | lane | via skill |
|---|---|---|---|
| An IG site, built from the AST on its cache branch | Restore and judge the cached AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Build and publish the site from the AST | Site build (agent, stage-local) | ig-build-pipeline |
| An IG site, built from the AST on its cache branch | Dispatch AST refresh | Publication 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-docs | Build each IG’s artefact index | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Generate each IG instance’s artefact pages | Host docs site build (CI runner) | ig-build-pipeline |
| Each IG, composed into a host docs site and rendered with just-the-docs | Clone each IG at its recorded commit and stage it | Host 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/ig-artifact-jsonld.ts. - 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.
| install | none |
| runtime | bun |
| network | no |
| when to choose it | |
|---|---|
| when | An IG’s pages are thin (the default of gen-ig-pages), or a consumer wants the artefacts as linked data. |
| limits | Identity and representations only, never the resource’s content: the resource is one of its encodings, fetched by the page. Upstream URLs are not fetched by check. |
| cost | Milliseconds per artefact. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/ig-artifact-jsonld/ig-artifact-jsonld.ts | |
| script | fhir-harness/scripts/ig-artifact-jsonld.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/fhir-harness/tools/ig-artifact-jsonld.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/ig-artifact-jsonld.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
"name": "ig-artifact-jsonld",
"title": "Write one JSON-LD node per IG artefact, and check a built site's nodes",
"description": "`write` turns an artefact index into `artifact/<Type>-<id>.jsonld` under a docs root, with no `.json` twin: one `folio-ig-artifact-jsonld/v1` node per artefact, in borrowed vocabularies only (the FHIR RDF class, dcterms, schema.org, PROV), naming the artefact's canonical URL, its representations and, for a compiled copy, what built it. With `--root-resources` (the IG site's default) the first representation is the reduced `<Type>-<id>.json` the site serves at its root (`local`), the second the full copy in the AST cache by raw URL (`mirror`), and each index entry names the root file (`schema:contentUrl`). `check` is the kind's QA: over a BUILT site, every artefact has its node and no node is an orphan, each node is its own file's, no `.json` twin is served beside it, and every local resource it names is on the site. It also writes and checks the index node, `artifact/index.jsonld` (`folio-ig-artifact-index-jsonld/v1`): every artefact once, each entry naming its node. These are the assets the thin pages render.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run fhir-harness/scripts/ig-artifact-jsonld.ts"
},
"io": {
"inputs": [
{
"name": "command",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "`write` or `check`.",
"required": true
},
{
"name": "index",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The `folio-fhir-artifact-index/v2` to write from, or to check against.",
"required": true
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`write`: the docs root the nodes go under.",
"required": false
},
{
"name": "dir",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`check`: the built docs root to check.",
"required": false
},
{
"name": "base",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Url",
"description": "`write`: the docs root's published URL, for absolute IRIs.",
"required": false
},
{
"name": "compiled-data",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "`write`: where compiled resource files are served, from the docs root, or the AST cache commit's raw base (then a `mirror`).",
"required": false
},
{
"name": "root-resources",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Flag",
"description": "`write`: the site serves each compiled resource at its root as `<Type>-<id>.json`; each node lists it first.",
"required": false
}
],
"outputs": [
{
"name": "nodes",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Count",
"description": "Nodes written, or checked; `check` exits 1 with each finding named."
}
]
},
"satisfies": [
"ig-build-pipeline"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"selection": {
"when": "An IG's pages are thin (the default of `gen-ig-pages`), or a consumer wants the artefacts as linked data.",
"limits": "Identity and representations only, never the resource's content: the resource is one of its encodings, fetched by the page. Upstream URLs are not fetched by `check`.",
"cost": "Milliseconds per artefact."
}
}