Check an IG’s built Questionnaires with CSIRO’s SDC libraries

Build-time Structured Data Capture checks, one result per Questionnaire (sdcChecks[] of fhir-questionnaire-wireframe): assemble (@aehrc/sdc-assemble 2.0.3: an assemble-root’s sub-forms resolve in this IG, and --out writes the assembled Questionnaire), template-extract (@aehrc/sdc-template-extract 1.0.16: extraction from the IG’s fixture response yields the expected resources), populate (@aehrc/sdc-populate 4.7.2: FHIRPath pre-population from a fixture context gives the expected answers) and behaviour (@aehrc/questionnaire-test-toolkit 0.1.0: the IG’s own behavioural test, warn-only). Checks only, no UI.

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.

fhir-questionnaire-wireframe

Source: fhir-harness/skills/content/fhir-ig-authoring/fhir-questionnaire-wireframe.md.

Also satisfied by: check-wireframe-questionnaire.

input [1..1]output [1..1]channels [0..*]screenshots [1..1]staging [0..1]candidates [1..*]chosen [0..1]renderer [1..1]pages [0..*]pages [0..*]checks [0..*]entries [0..*]fidelity [0..*]sdcChecks [0..*]changeRequests [0..*]changedAssets [0..*]stagingLinks [1..1]fhir-questionnaire-wireframe«skill»fhir-questionnaire-wireframeinput : FHIRQuestionnaireWireframeInput [1..1]output : FHIRQuestionnaireWireframeOutput [1..1]FHIRQuestionnaireWireframeInput«json-schema»FHIRQuestionnaireWireframeInputquestionnaire : string [1..1]mode : "render" | "fidelity-check" | "wireframe-from-que… [0..1]wireframe : string [0..1]renderer : "lhc-forms" [0..1]assetDir : string [0..1]suggest : boolean [0..1]issueForm : string [0..1]channels : FHIRQuestionnaireWireframeInput.channels[] [0..*]branch : string [0..1]FHIRQuestionnaireWireframeInput.channels«json-schema»FHIRQuestionnaireWireframeInput.channelskind : "conversation" | "issue" | "pull-request" [1..1]url : string [0..1]FHIRQuestionnaireWireframeOutput«json-schema»FHIRQuestionnaireWireframeOutputuse : "design" | "as-is" [1..1]topic : string [1..1]assetDir : string [1..1]intent : string [0..1]candidates : FHIRQuestionnaireWireframeOutput.candidates… [1..*]chosen : FHIRQuestionnaireWireframeOutput.chosen [0..1]questionnaire : string [0..1]renderer : FHIRQuestionnaireWireframeOutput.renderer [1..1]fidelity : fidelityEntry[] [0..*]sdcChecks : sdcCheckResult[] [0..*]… 3 moreFHIRQuestionnaireWireframeOutput.candidates.screenshots«json-schema»FHIRQuestionnaireWireframeOutput.candidates.screenshotsweb : string [1..1]mobile : string [1..1]FHIRQuestionnaireWireframeOutput.candidates.staging«json-schema»FHIRQuestionnaireWireframeOutput.candidates.stagingsource : string [0..1]web : string [0..1]mobile : string [0..1]FHIRQuestionnaireWireframeOutput.candidates«json-schema»FHIRQuestionnaireWireframeOutput.candidatesid : string [1..1]title : string [0..1]source : string [1..1]screenshots : FHIRQuestionnaireWireframeOutput.candidate… [1..1]staging : FHIRQuestionnaireWireframeOutput.candidates.st… [0..1]entries : criterionEntry[] [0..*]outcome : "chosen" | "rejected" | "pending" | "as-is" [1..1]reason : string [0..1]FHIRQuestionnaireWireframeOutput.chosen«json-schema»FHIRQuestionnaireWireframeOutput.chosencandidate : string [1..1]chosenBy : string [1..1]recordedAt : string [0..1]FHIRQuestionnaireWireframeOutput.renderer«json-schema»FHIRQuestionnaireWireframeOutput.renderername : "lhc-forms" [1..1]version : string [1..1]assets : string [0..1]licenceNotice : string [0..1]criterionEntry«json-schema»criterionEntrycriterion : string [1..1]status : "pass" | "warn" | "fail" [1..1]by : string [0..1]note : string [0..1]fidelityEntry«json-schema»fidelityEntryquestionnaire : string [1..1]wireframe : string [0..1]layout : string [1..1]status : "faithful" | "findings" | "could-not-determine" [1..1]findings : string[] [0..*]changeRequest«json-schema»changeRequestissue : string [1..1]via : "suggest" | "issue-form" [0..1]questionnaire : string [0..1]edited : "questionnaire" | "wireframe" [1..1]status : "received" | "triaged" | "applied" | "staged" |… [1..1]note : string [0..1]changedAsset.pages«json-schema»changedAsset.pagestitle : string [1..1]before : string [0..1]after : string [0..1]summary : string [0..1]changedAsset«json-schema»changedAssetchange : "added" | "changed" | "removed" [1..1]kind : string [0..1]title : string [0..1]before : string [0..1]after : string [0..1]source : string [0..1]pages : changedAsset.pages[] [0..*]pagesUnknown : string [0..1]stagingLinks.pages«json-schema»stagingLinks.pagestitle : string [1..1]before : string [0..1]after : string [0..1]summary : string [0..1]stagingLinks«json-schema»stagingLinksbranch : string [1..1]slug : string [1..1]branchUrl : string [1..1]pr : integer [0..1]mainBaseUrl : string [1..1]stagingBaseUrl : string [1..1]pages : stagingLinks.pages[] [0..*]missing : string[] [0..*]sdcCheckResult.checks«json-schema»sdcCheckResult.checkscheck : "assemble" | "template-extract" | "populate" | "… [1..1]library : string [1..1]status : "pass" | "fail" | "not-applicable" | "no-fixtur… [1..1]severity : "error" | "warning" [1..1]findings : string[] [0..*]output : string [0..1]sdcCheckResult«json-schema»sdcCheckResultquestionnaire : string [1..1]checks : sdcCheckResult.checks[] [0..*]

input — fhir-harness/schemas/skills/fhir-questionnaire-wireframe/input.schema.json, https://litlfred.github.io/folio-assistant/fhir-harness/skills/fhir-questionnaire-wireframe/input.schema.json

fieldtyperequireddescription
questionnairestringyesRepository-relative path of ONE built Questionnaire JSON (fsh-generated/resources/Questionnaire-<id>.json), never FSH. Several Questionnaires are several runs, so each carries its own fidelity findings and review.
moderender \| fidelity-check \| wireframe-from-questionnairerender: wireframe and form view for review. fidelity-check: only the field-for-field check against wireframe. wireframe-from-questionnaire: draw an L2 wireframe from a Questionnaire that has none.
wireframestringRepository-relative path of the L2 wireframe HTML the Questionnaire was derived from (the chosen wireframe-design-review candidate), when one exists.
rendererlhc-formsThe form-view renderer. Only the vendored NLM LHC-Forms (owner, 2026-10-14).
assetDirstringRepository-relative directory for the wireframes, captures and checks.
suggestbooleanOffer ✍ suggest, in its Questionnaire mode, on the form view.
issueFormstringThe issue form change requests are opened with.
channelsobject[]Where the request for review goes: chosen by judgement, and more than one may be right (staging-review, the deep-link rule, point 5).
branchstringThe feature branch the renderings are committed on, so feature-staging publishes them.

output — fhir-harness/schemas/skills/fhir-questionnaire-wireframe/output.schema.json, https://litlfred.github.io/folio-assistant/fhir-harness/skills/fhir-questionnaire-wireframe/output.schema.json

fieldtyperequireddescription
usedesign \| as-isyes
topicstringyes
assetDirstringyesRepository-relative directory holding the wireframes, the form-view captures and their checks.
intentstringRepository-relative path of intent.md.
candidatesobject[]yesAt least two for Design use, exactly one (marked as-is) for as-is use.
chosenobjectDesign use: the candidate the human reviewer chose. Absent until they choose; an agent never records a choice on a person’s behalf.
questionnairestringThe built Questionnaire JSON rendered, as in the input.
rendererobjectyesWhat drew the form view. The vendored build, never a CDN at runtime (owner, 2026-10-14).
fidelityfidelityEntry[]check-wireframe-questionnaire’s findings, one entry per Questionnaire and wireframe layout. Absent when no L2 wireframe exists; an entry whose status is could-not-determine (exit 2) is never a pass.
sdcCheckssdcCheckResult[]The SDC build checks (fhir-harness sdc-checks, CSIRO’s libraries), one entry per Questionnaire. not-applicable, no-fixture and could-not-determine are never a pass; a behavioural test’s failure is a warning.
changeRequestschangeRequest[]Change requests received through ✍ suggest or the questionnaire-change issue form, and where each stands.
changedAssetschangedAsset[]yesEvery file the branch adds, changes or removes — wireframe HTML, form-view pages, screenshots, reviews — in the changed-assets record shape a staging preview’s graph carries.
stagingLinksstagingLinksyes

Inputs and outputs

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

porttyperequireddescriptionconstraint
inastFilesystemPathyesThe IG’s FHIR AST (output-ast/): its Questionnaires, and the canonicals a sub-form resolves against.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inquestionnaireTextA Questionnaire id to check; default every one in the AST.string · A short single-line human string. Not admissible as a command-line argument.
infixturesFilesystemPathOne directory per Questionnaire id: response.json + extract-expected.json, populate-context.json + populate-expected.json, behaviour.test.tsx.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inoutFilesystemPathWhere assembled Questionnaires are written.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
outsdcChecksTextPer Questionnaire, per check: pass, fail, not-applicable, no-fixture or could-not-determine — the last three never a pass. JSON with --json. Exit 1 on an error-severity failure; behavioural tests never fail the run.string · A short single-line human string. 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
Questionnaire wireframe reviewRead the built Questionnaire JSONFHIR modellerfhir-questionnaire-wireframe
Questionnaire wireframe reviewRender the wireframe and the LHC-Forms viewFHIR modellerfhir-questionnaire-wireframe
Questionnaire wireframe reviewCheck field for fieldBuild pipeline — rendering, screenshots, fidelityfhir-questionnaire-wireframe
Questionnaire wireframe reviewReview the staged form and wireframeClinical reviewer — the staged formfhir-questionnaire-wireframe
SMART Guideline end to endReview each L3 asset (before / after if adapted)Human adjudicatorsfhir-questionnaire-wireframe

How it is deployed and reached

  • Command line. From the repository root: bun run fhir-harness/scripts/sdc-checks.ts --ast <ast> [--questionnaire <id>] [--fixtures <dir>] [--out <dir>] [--json].
  • 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
whenAfter SUSHI has built the IG’s Questionnaires and before they are reviewed as forms; whenever a Questionnaire uses modular sub-forms, template extraction or pre-population.
limitsOnly as good as the IG’s fixtures: with none, extraction and population say no-fixture rather than pass. Nothing is fetched from a server: sub-forms resolve in the AST and population queries in the fixture. The behavioural toolkit is early and needs React and Smart Forms peers installed with the IG’s tests; without them it is could-not-determine, a warning.
costSeconds per Questionnaire; a behavioural test runs a bun test process.

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/sdc-checks.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/sdc-checks.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
  "name": "sdc-checks",
  "title": "Check an IG's built Questionnaires with CSIRO's SDC libraries",
  "description": "Build-time Structured Data Capture checks, one result per Questionnaire (`sdcChecks[]` of `fhir-questionnaire-wireframe`): `assemble` (`@aehrc/sdc-assemble` 2.0.3: an assemble-root's sub-forms resolve in this IG, and `--out` writes the assembled Questionnaire), `template-extract` (`@aehrc/sdc-template-extract` 1.0.16: extraction from the IG's fixture response yields the expected resources), `populate` (`@aehrc/sdc-populate` 4.7.2: FHIRPath pre-population from a fixture context gives the expected answers) and `behaviour` (`@aehrc/questionnaire-test-toolkit` 0.1.0: the IG's own behavioural test, warn-only). Checks only, no UI.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run fhir-harness/scripts/sdc-checks.ts --ast <ast> [--questionnaire <id>] [--fixtures <dir>] [--out <dir>] [--json]"
  },
  "io": {
    "inputs": [
      {
        "name": "ast",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "The IG's FHIR AST (`output-ast/`): its Questionnaires, and the canonicals a sub-form resolves against.",
        "required": true
      },
      {
        "name": "questionnaire",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "A Questionnaire id to check; default every one in the AST.",
        "required": false
      },
      {
        "name": "fixtures",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "One directory per Questionnaire id: `response.json` + `extract-expected.json`, `populate-context.json` + `populate-expected.json`, `behaviour.test.tsx`.",
        "required": false
      },
      {
        "name": "out",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
        "description": "Where assembled Questionnaires are written.",
        "required": false
      }
    ],
    "outputs": [
      {
        "name": "sdcChecks",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "Per Questionnaire, per check: pass, fail, not-applicable, no-fixture or could-not-determine — the last three never a pass. JSON with `--json`. Exit 1 on an error-severity failure; behavioural tests never fail the run."
      }
    ]
  },
  "satisfies": [
    "fhir-questionnaire-wireframe"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "After SUSHI has built the IG's Questionnaires and before they are reviewed as forms; whenever a Questionnaire uses modular sub-forms, template extraction or pre-population.",
    "limits": "Only as good as the IG's fixtures: with none, extraction and population say `no-fixture` rather than pass. Nothing is fetched from a server: sub-forms resolve in the AST and population queries in the fixture. The behavioural toolkit is early and needs React and Smart Forms peers installed with the IG's tests; without them it is `could-not-determine`, a warning.",
    "cost": "Seconds per Questionnaire; a behavioural test runs a bun test process."
  }
}

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