Export an IG AST as JSON-LD

Write an AST as linked data against fhir-harness/schemas/ig-ast.context.jsonld: each resource a node identified by its canonical URL (urn:fhir:<Type>/<id> when it has none) and typed by its FHIR resource type, each dependency edge a link to its target, and the manifest’s authority: cache and provisional list carried on the graph. The AST is validated against the Zod declaration the JSON Schemas are generated from before it is exported.

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-ast-delta

List and view what changed between two IG ASTs, check whether an AST is still valid for the IG’s current inputs, and render the delta as just-the-docs pages that carry the provisional mark. Read before trusting a cached AST, before reviewing an incremental IG build, and before rendering anything from a cache.

Source: fhir-harness/skills/fhir-ig-base/ig-ast-delta.md.

Also satisfied by: ig-ast-diff, ig-ast-list, ig-ast-pages, ig-ast-plan, ig-ast-render, ig-ast-validity, ig-cache.

The skill declares no I/O contract (schemas/skills/ig-ast-delta/{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
inastFilesystemPathyesstring · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
outjsonldFilesystemPathJSON-LD 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
Is the incremental IG AST what a full build would have produced?Check the base AST against the inputsIncremental build (system)ig-ast-delta
Is the incremental IG AST what a full build would have produced?Diff the two ASTsIncremental build (system)ig-ast-delta
Is the incremental IG AST what a full build would have produced?Read the deltaQC reviewerig-ast-delta
An IG site, built from the AST on its cache branchRestore and judge the cached ASTSite build (agent, stage-local)ig-ast-delta
SMART Guideline end to endReview each L3 asset (before / after if adapted)Human adjudicatorsig-ast-delta

How it is deployed and reached

  • Command line. From the repository root: bun run fhir-harness/scripts/ig-ast.ts jsonld <ast> > ast.jsonld.
  • GitHub Actions. 11 workflow line(s) run its command:
workflowline
fhir-harness/.github/workflows/ig-ast-refresh.yml173bun run fhir-harness/scripts/ig-ast.ts validity output-ast --ig . > "$RUNNER_TEMP/ast-validity.json"
fhir-harness/.github/workflows/ig-ast-refresh.yml177bun run fhir-harness/scripts/ig-ast.ts cache-line output-ast --ig . 2>/dev/null \|\| true
fhir-harness/.github/workflows/ig-ast-refresh.yml199kind=$(bun run fhir-harness/scripts/ig-ast.ts build-kind output-ast 2>/dev/null \|\| echo full)
fhir-harness/.github/workflows/ig-ast-refresh.yml427&& bun run fhir-harness/scripts/ig-ast.ts validity output-ast --ig . > /dev/null; then
fhir-harness/.github/workflows/ig-ast-refresh.yml430kind=$(bun run fhir-harness/scripts/ig-ast.ts build-kind output-ast 2>/dev/null \|\| echo incremental)
fhir-harness/.github/workflows/ig-ast-refresh.yml433bun run fhir-harness/scripts/ig-ast.ts cache-line output-ast --ig . --warm 2>/dev/null \|\| true
fhir-harness/.github/workflows/ig-ast-refresh.yml459source_digest=$(bun run fhir-harness/scripts/ig-ast.ts digest --ig .) \\
fhir-harness/.github/workflows/ig-ast-refresh.yml498now=$(bun run fhir-harness/scripts/ig-ast.ts digest --ig .)
fhir-harness/.github/workflows/ig-ast-refresh.yml501bun run fhir-harness/scripts/ig-ast.ts source-inputs output-ast --digest "$source_digest" --pre-export "$PRE_EXPORT"
fhir-harness/.github/workflows/ig-ast-refresh.yml505bun run fhir-harness/scripts/ig-ast.ts validity output-ast --ig . \\
fhir-harness/.github/workflows/ig-release.yml123bun run fhir-harness/scripts/ig-ast.ts build-kind "$IN/output-ast" --require-full

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

installnone
runtimebun
networkno
when to choose it
whenHanding an AST to a consumer that reads linked data, or joining it with another graph by canonical URL.
limitsExports the manifest and edges, not each resource’s full JSON; a consumer that needs the resource body reads its file. Still a cache: the export carries the provisional mark, it does not remove it.
costReads the manifest and dependency document once.

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/ig-ast-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-ast-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-ast-jsonld",
  "title": "Export an IG AST as JSON-LD",
  "description": "Write an AST as linked data against `fhir-harness/schemas/ig-ast.context.jsonld`: each resource a node identified by its canonical URL (`urn:fhir:<Type>/<id>` when it has none) and typed by its FHIR resource type, each dependency edge a link to its target, and the manifest's `authority: cache` and `provisional` list carried on the graph. The AST is validated against the Zod declaration the JSON Schemas are generated from before it is exported.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/ig-ast.ts jsonld <ast> > ast.jsonld"
  },
  "io": {
    "inputs": [
      {
        "name": "ast",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "required": true
      }
    ],
    "outputs": [
      {
        "name": "jsonld",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "JSON-LD on stdout."
      }
    ]
  },
  "satisfies": [
    "ig-ast-delta"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "Handing an AST to a consumer that reads linked data, or joining it with another graph by canonical URL.",
    "limits": "Exports the manifest and edges, not each resource's full JSON; a consumer that needs the resource body reads its `file`. Still a cache: the export carries the provisional mark, it does not remove it.",
    "cost": "Reads the manifest and dependency document once."
  }
}

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