Separate the definition, answers, score, and report
A psychometric workflow can produce four related but distinct artifacts. Questionnaire defines what was asked and how items are organised. QuestionnaireResponse records what was answered for a subject on a particular occasion. Observation is designed for measurements and simple assertions, including some clinical assessment tool results. DiagnosticReport provides clinical and workflow context around a set of results, but is not a default wrapper for every assessment document. [1][2][3][4]
Treat Questionnaire as a versioned definition
Give the Questionnaire a stable canonical identity and a meaningful version. Maintain stable linkId values within a version because QuestionnaireResponse uses them to connect answers to questions. Record status, subject type, item types, enablement rules, answer constraints, and terminology bindings that a receiver needs to validate or render the form. [1][2]
- Do not silently replace one instrument edition with another under the same version.
- Represent display text and structure accurately enough for the intended receiver, while respecting instrument licensing.
- Profile required identifiers, canonical references, and supported item types when the base resource is too permissive.
- Test amendments and retired versions so historic responses remain interpretable.
The assessment artifact chain in FHIR
A four-step flow separating a versioned instrument definition, one administration's answers, derived results, and a report selected for its workflow meaning.
- Define
Questionnaire records the versioned form, item structure, constraints, and codes.
- Capture
QuestionnaireResponse records one subject's answers, status, time, and provenance.
- Derive
Observation records a governed score or subscale with explicit meaning and method.
- Present
DiagnosticReport or a document pattern provides the appropriate clinical narrative context.
Preserve response context and provenance
A QuestionnaireResponse should reference the Questionnaire definition where possible and carry subject, author or source context, encounter when relevant, authored time, and status. The item hierarchy and linkId relationships must remain consistent with the referenced Questionnaire. A new administration normally creates a distinct response rather than overwriting an earlier occasion. [2]
- Distinguish in-progress, completed, amended, stopped, and entered-in-error states.
- Keep unanswered, not-applicable, and unknown meanings distinct rather than converting them all to zero.
- Validate item cardinality and answer data types against the referenced definition.
- Apply access controls to both answers and attachments because they may contain sensitive health information.
- Questionnaire/example-wellbeing-v1 has canonical URL https://example.invalid/fhir/Questionnaire/example-wellbeing, version 1.0, and one integer item with linkId mood-1.
- QuestionnaireResponse/response-001 references that canonical Questionnaire version, uses subject Patient/synthetic-001, status completed, and records answerInteger 2 under linkId mood-1.
- Observation/score-001 uses the same synthetic subject, records valueInteger 2 under a governed example score code, and points derivedFrom to QuestionnaireResponse/response-001.
- DiagnosticReport/report-001 uses the same synthetic subject and points result to Observation/score-001 when the receiving workflow genuinely treats the artifact as a diagnostic service report.
Model derived scores without losing meaning
Observation can carry a total or subscale score when the code identifies what was calculated, value and units or scale are explicit, effective time reflects the assessment occasion, and method or component data provide necessary context. Use derivedFrom to connect a score to supporting resources where the implementation profile permits it. Do not encode a screening score as a diagnosis. [3]
Choose the report pattern and validate end to end
DiagnosticReport can reference atomic Observation results and include narrative or a presented form when the artifact functions as a diagnostic service report. For a clinician-authored narrative document, Composition and a document Bundle may fit better. Decide from the workflow meaning and receiver requirements, not from the convenience of attaching a PDF. [4][5]
- Validate resources against the agreed FHIR version, profiles, terminology, and business rules.
- Test references, identifiers, amendments, duplicate submission, missing optional fields, and unsupported codes.
- Render a clinically safe human view and compare it with the structured data for consistency.
- Confirm the receiving server's CapabilityStatement and implementation guide rather than assuming base R4 support is sufficient.
Sources and further reading
- FHIR R4 Questionnaire (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Base resource definition and boundaries for questionnaire content.
- FHIR R4 QuestionnaireResponse (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Base resource definition, status model, linking rules, and security notes for answers.
- FHIR R4 Observation (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Normative R4 model and boundaries for measurements and simple assertions.
- FHIR R4 DiagnosticReport (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official report model, result relationships, and boundary guidance.
- FHIR R4 Documents (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official guidance for Composition-led document Bundles.
- FHIR R4 Using Codes (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official guidance on code systems, value sets, bindings, and mappings.
- FHIR R4 CapabilityStatement (opens in a new tab)HL7 International. Updated 2019-11-01. Accessed 2026-07-13. Official model for declaring supported resource and interaction behavior.