Questionnaire — The FHIR structured form

PHQ-9, clinical-trial eCRF, admission form, patient PRO: Questionnaire is the pivot resource of the structured clinical form. Over 600 public instruments indexed on LOINC.

Purpose

Questionnaire is the definition of a form: hierarchical items, answer types, constraints, conditional jump logic (enableWhen), pre-coded answers. The actual data entered by patient or clinician goes in a QuestionnaireResponse that points to this Questionnaire.

The Structured Data Capture (SDC) IG published by HL7 enriches Questionnaire with extensions for rendering (display as grid, slider), pre-population from other FHIR resources, and auto-export to Observation / Condition after submission.

Key fields

Item types

The item.type binding is required:

• group — group of items.
• display — informational text, no answer.
• boolean — Yes/No.
• decimal, integer — numbers.
• date, dateTime, time.
• string, text — short / long text.
• url — URL.
• choice, open-choice — selection (with other).
• attachment — attachment.
• reference — reference to another FHIR resource.
• quantity — value + unit.
• coding — code alone (R5).

JSON example

Excerpt of PHQ-9 (Patient Health Questionnaire), 9 LOINC items, score 0–27. Items 1 and 2 carry answers via answerOption and answerValueSet respectively:

{
  "resourceType": "Questionnaire",
  "id": "phq9",
  "url": "http://example.org/Questionnaire/phq9",
  "version": "1.0.0",
  "name": "PHQ9",
  "title": "Patient Health Questionnaire (PHQ-9)",
  "status": "active",
  "subjectType": ["Patient"],
  "date": "2026-05-14",
  "publisher": "Example Org",
  "code": [{
    "system": "http://loinc.org",
    "code": "44249-1",
    "display": "PHQ-9 quick depression assessment panel"
  }],
  "item": [
    {
      "linkId": "1",
      "code": [{ "system": "http://loinc.org", "code": "44250-9" }],
      "text": "Over the last 2 weeks, how often have you had little interest or pleasure in doing things?",
      "type": "choice",
      "required": true,
      "answerOption": [
        { "valueCoding": { "system": "http://loinc.org/LL358-3", "code": "LA6568-5", "display": "Not at all" }, "extension": [{ "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue", "valueDecimal": 0 }] },
        { "valueCoding": { "system": "http://loinc.org/LL358-3", "code": "LA6569-3", "display": "Several days" }, "extension": [{ "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue", "valueDecimal": 1 }] },
        { "valueCoding": { "system": "http://loinc.org/LL358-3", "code": "LA6570-1", "display": "More than half the days" }, "extension": [{ "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue", "valueDecimal": 2 }] },
        { "valueCoding": { "system": "http://loinc.org/LL358-3", "code": "LA6571-9", "display": "Nearly every day" }, "extension": [{ "url": "http://hl7.org/fhir/StructureDefinition/ordinalValue", "valueDecimal": 3 }] }
      ]
    },
    {
      "linkId": "2",
      "text": "Over the last 2 weeks, how often have you felt down, depressed, or hopeless?",
      "type": "choice",
      "required": true,
      "answerValueSet": "http://loinc.org/vs/LL358-3"
    },
    {
      "linkId": "10",
      "text": "PHQ-9 total score",
      "type": "integer",
      "readOnly": true
    }
  ]
}

Common pitfalls

• Missing or duplicated linkId — every item MUST have a unique linkId. QuestionnaireResponse matches items by linkId.
• group type with an answer — a group never carries an answer, only sub-items.
• required=true without enableWhen — a required, visible, unfilled item blocks submission.
• Manual scoring — for PROMs (PHQ-9, MoCA, KCCQ...), use the SDC extension questionnaire-calculatedExpression to compute the score.
• LOINC copyright not respected — cite the LOINC code of the instrument and the cited instrument version in code.

Related resources

• QuestionnaireResponse — patient or clinician answers to this Questionnaire.
• Observation — may be created from SDC items.
• ValueSet — referenced by answerValueSet.
• Library — CQL/FHIRPath scoring logic.