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 [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
inwireframeFilesystemPathyesThe wireframe HTML; fields carry data-element, layouts data-layout.string · A filesystem path, possibly outside the repository. Not admissible as a command-line argument.
inquestionnaireFilesystemPathyesThe 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.
outfindingsTextOne 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:

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/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.

installnone
runtimebun
networkno
when to choose it
whenA 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).
limitsCompares 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.
costMilliseconds; reads two files.

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/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."
  }
}

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