Check a Questionnaire field for field against the wireframe it was derived from
Compare the data-element fields of a mid-fidelity wireframe (per data-layout, in document order) with the answerable items of a BUILT Questionnaire (depth first, named by definition or code). Reports a field with no item, an item with no field, an item naming no data element, a data element twice in one layout, and the first place the order differs. Fidelity, not design.
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: sdc-checks.
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
| field | type | required | description |
|---|---|---|---|
questionnaire | string | yes | Repository-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. |
mode | render \| fidelity-check \| wireframe-from-questionnaire | render: 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. | |
wireframe | string | Repository-relative path of the L2 wireframe HTML the Questionnaire was derived from (the chosen wireframe-design-review candidate), when one exists. | |
renderer | lhc-forms | The form-view renderer. Only the vendored NLM LHC-Forms (owner, 2026-10-14). | |
assetDir | string | Repository-relative directory for the wireframes, captures and checks. | |
suggest | boolean | Offer ✍ suggest, in its Questionnaire mode, on the form view. | |
issueForm | string | The issue form change requests are opened with. | |
channels | object[] | Where the request for review goes: chosen by judgement, and more than one may be right (staging-review, the deep-link rule, point 5). | |
branch | string | The 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
| field | type | required | description |
|---|---|---|---|
use | design \| as-is | yes | |
topic | string | yes | |
assetDir | string | yes | Repository-relative directory holding the wireframes, the form-view captures and their checks. |
intent | string | Repository-relative path of intent.md. | |
candidates | object[] | yes | At least two for Design use, exactly one (marked as-is) for as-is use. |
chosen | object | Design use: the candidate the human reviewer chose. Absent until they choose; an agent never records a choice on a person’s behalf. | |
questionnaire | string | The built Questionnaire JSON rendered, as in the input. | |
renderer | object | yes | What drew the form view. The vendored build, never a CDN at runtime (owner, 2026-10-14). |
fidelity | fidelityEntry[] | 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. | |
sdcChecks | sdcCheckResult[] | 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. | |
changeRequests | changeRequest[] | Change requests received through ✍ suggest or the questionnaire-change issue form, and where each stands. | |
changedAssets | changedAsset[] | yes | Every 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. |
stagingLinks | stagingLinks | yes |
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 | wireframe | FilesystemPath | yes | The wireframe HTML; fields carry data-element, layouts data-layout. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. |
| in | questionnaire | FilesystemPath | yes | The built Questionnaire JSON (fsh-generated/resources/Questionnaire-<id>.json), never FSH. | string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument. |
| out | findings | Text | One line per finding, prefixed with its layout. Exit 0 faithful, 1 a finding, 2 an input could not be read (never a pass). | 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:
| process | step | lane | via skill |
|---|---|---|---|
| Questionnaire wireframe review | Read the built Questionnaire JSON | FHIR modeller | fhir-questionnaire-wireframe |
| Questionnaire wireframe review | Render the wireframe and the LHC-Forms view | FHIR modeller | fhir-questionnaire-wireframe |
| Questionnaire wireframe review | Check field for field | Build pipeline — rendering, screenshots, fidelity | fhir-questionnaire-wireframe |
| Questionnaire wireframe review | Review the staged form and wireframe | Clinical reviewer — the staged form | fhir-questionnaire-wireframe |
| SMART Guideline end to end | Review each L3 asset (before / after if adapted) | Human adjudicators | fhir-questionnaire-wireframe |
How it is deployed and reached
- Command line. From the repository root:
bun run fhir-harness/scripts/check-wireframe-questionnaire.ts <wireframe> <questionnaire>. - 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 | A Questionnaire was derived from an L2 wireframe and is reviewed for fidelity; or a suggested edit to either side is checked (checkSuggestion, the same judge in the editor-checker shape). |
| limits | Compares ids and order only: it says nothing about labels, answer options, enableWhen or layout quality, which wireframe-design-review judges. A wireframe with no data-element field is exit 2, not a pass. |
| cost | Milliseconds; reads two files. |
What it is made of
| role | file | |
|---|---|---|
| definition | fhir-harness/tools/check-wireframe-questionnaire/check-wireframe-questionnaire.ts | |
| script | fhir-harness/scripts/check-wireframe-questionnaire.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/check-wireframe-questionnaire.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/check-wireframe-questionnaire.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/fhir-harness/fhir-harness.jsonld",
"name": "check-wireframe-questionnaire",
"title": "Check a Questionnaire field for field against the wireframe it was derived from",
"description": "Compare the `data-element` fields of a mid-fidelity wireframe (per `data-layout`, in document order) with the answerable items of a BUILT Questionnaire (depth first, named by `definition` or `code`). Reports a field with no item, an item with no field, an item naming no data element, a data element twice in one layout, and the first place the order differs. Fidelity, not design.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run fhir-harness/scripts/check-wireframe-questionnaire.ts <wireframe> <questionnaire>"
},
"io": {
"inputs": [
{
"name": "wireframe",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "The wireframe HTML; fields carry `data-element`, layouts `data-layout`.",
"required": true
},
{
"name": "questionnaire",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/FilesystemPath",
"description": "The built Questionnaire JSON (`fsh-generated/resources/Questionnaire-<id>.json`), never FSH.",
"required": true
}
],
"outputs": [
{
"name": "findings",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
"description": "One line per finding, prefixed with its layout. Exit 0 faithful, 1 a finding, 2 an input could not be read (never a pass)."
}
]
},
"satisfies": [
"fhir-questionnaire-wireframe"
],
"requirements": {
"runtime": [
"bun"
],
"network": false
},
"selection": {
"when": "A Questionnaire was derived from an L2 wireframe and is reviewed for fidelity; or a suggested edit to either side is checked (`checkSuggestion`, the same judge in the editor-checker shape).",
"limits": "Compares ids and order only: it says nothing about labels, answer options, enableWhen or layout quality, which `wireframe-design-review` judges. A wireframe with no `data-element` field is exit 2, not a pass.",
"cost": "Milliseconds; reads two files."
}
}