| name | include-instrument |
| description | Decide whether to inline a validated instrument (copy items into Questionnaire.json) versus reference it via subQuestionnaire. Surfaces license + fidelity tradeoffs and records the decision. Use when the user wants to "add PHQ-9" (or any published instrument) to a draft. |
Include instrument
When to use this
- The user names a published instrument ("add PHQ-9", "include
GAD-7") and you need to actually wire it in.
- A research turn surfaced a candidate instrument the user is
about to accept.
Two ways to include
A. Inline (copy items)
Copy the instrument's items directly into the form's item[].
- ✅ Self-contained: the form ships with everything the patient
sees.
- ✅ Easy to localize and re-skin.
- ❌ Drifts from the canonical source over time.
- ❌ License risk for non-public-domain instruments.
B. subQuestionnaire reference
Use the SDC subQuestionnaire extension on a display (or
group) item:
{
"linkId": "phq9",
"type": "display",
"extension": [{
"url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-subQuestionnaire",
"valueCanonical": "http://loinc.org/q/44249-1"
}]
}
- ✅ Renderer pulls the canonical version each time.
- ✅ License-clean: you're referencing, not copying.
- ❌ Renderer support varies. Pin a renderer or test before
shipping.
License triage
| License | Approach |
|---|
| Public domain (PHQ-9, GAD-7, AUDIT, SF-36 v1) | Inline OK. |
| Free-with-attribution (NIH PROMIS short forms; many AHRQ) | Inline OK; preserve attribution copy. |
| Permission required (BDI-II, HADS, some PROMIS CAT) | subQuestionnaire only. Note license in decisions.md. |
| Trade secret | Don't include. Refuse and explain. |
Always cite the source instrument in the form via an
instrument-typed citation (refType=instrument,
refId=valueCanonical) regardless of method.
Recording the decision
After including (or referencing) an instrument, append to
decisions.md:
2026-05-12 — Included PHQ-9 inline. Public domain in this
jurisdiction. Source: USPSTF
https://www.uspreventiveservicestaskforce.org/.../phq-9.
Pitfalls
- Modifying the wording of a copyrighted instrument and shipping
the modification ("just simplifying it"). Don't.
- Inlining an instrument without recording the decision — when the
user re-asks "where did this come from?" later, the conversation
log may have been compacted away.
- Mixing instrument items with locally-authored items in the same
group. Keep them in their own group with a
display-typed
attribution header.
