Admin: Automated edit (via update-page on MediaWiki MCP Server)

2026-07-06T04:05:59Z

Automated edit (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:35, 6 July 2026
Line 194:		Line 194:
	* <code>FormSubmission</code> runs a draft→submitted lifecycle. Its <code>response_dump</code> is opaque JSON — the questionnaire definition validates it, the model does not.		* <code>FormSubmission</code> runs a draft→submitted lifecycle. Its <code>response_dump</code> is opaque JSON — the questionnaire definition validates it, the model does not.
	* The server maintains the audit users (<code>created_by</code>/<code>updated_by</code>); don't set them on write.		* The server maintains the audit users (<code>created_by</code>/<code>updated_by</code>); don't set them on write.

			{{Navbox clinical}}

	{{Related}}		{{Related}}
			Wiki: ohcnwiki.tellmey.fyi

Admin: OHC identity seed

2026-07-04T22:44:31Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Questionnaire Response
|order=14
|introduced=3.0
|fhir=QuestionnaireResponse
|model=QuestionnaireResponse
|concept=Concepts/Patient
|reference=References/Encounter
}}

A <code>QuestionnaireResponse</code> is the set of answers a patient gives to a [[References/Questionnaire|questionnaire]]; a <code>FormSubmission</code> is the envelope that carries that payload through a draft-to-finalised lifecycle. You touch these when reading back what was answered or when submitting new answers.

The Django models are the storage; the Pydantic resource specs define the submit payload, answer structure, status enums, and read/write API schemas.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/questionnaire.py <code>care/emr/models/questionnaire.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/questionnaire_response/spec.py <code>resources/questionnaire_response/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/form_submission/spec.py <code>resources/form_submission/spec.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>QuestionnaireResponse</code>
| A completed set of answers to a <code>Questionnaire</code> for a subject (patient/encounter)
|-
| <code>FormSubmission</code>
| A submission envelope (draft → submitted) holding a raw response dump for a questionnaire
|}

Both extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that provides <code>external_id</code>, audit fields, soft-delete via <code>deleted</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>QuestionnaireResponse</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=questionnaire|type=FK → Questionnaire|notes=<code>CASCADE</code>, nullable. The questionnaire that was answered}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=subject_id|type=UUIDField|notes=The subject the response is about (e.g. patient external id)}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=responses|type=JSONField|notes=<code>default=list</code>. The raw answers — a list of <code>{ "question_id": UUID, ... }</code> entries}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=structured_responses|type=JSONField|notes=<code>default=dict</code>. Extracted/structured representation of the answers}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=structured_response_type|type=CharField|notes=Nullable. Discriminator for the structured payload}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=patient|type=FK → Patient|notes=<code>CASCADE</code>. The patient}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=encounter|type=FK → Encounter|notes=<code>CASCADE</code>, nullable. Set when the response is captured in a visit context}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=form_submission|type=FK → FormSubmission|notes=<code>CASCADE</code>, nullable. The submission this response came from}}
{{Field|model=QuestionnaireResponse|section=QuestionnaireResponse fields|name=status|type=CharField(255)|notes=<code>default="completed"</code>. One of <code>QuestionnaireResponseStatusChoices</code> (see [[#questionnaire-response-status}}
|}

=== <code>render_responses()</code> ===

Joins each entry in <code>responses</code> with its matching question definition from <code>questionnaire.get_questions_by_id()</code>, returning a list of <code>{ "answer": <response>, "question": <question> }</code> for display. Returns <code>[]</code> when <code>responses</code> is empty or no questionnaire is linked.

== <code>FormSubmission</code> fields ==

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=QuestionnaireResponse|section=FormSubmission fields|name=questionnaire|type=FK → Questionnaire|notes=<code>CASCADE</code>. The questionnaire being submitted}}
{{Field|model=QuestionnaireResponse|section=FormSubmission fields|name=patient|type=FK → Patient|notes=<code>CASCADE</code>. The patient}}
{{Field|model=QuestionnaireResponse|section=FormSubmission fields|name=encounter|type=FK → Encounter|notes=<code>CASCADE</code>, nullable. Encounter context, if any}}
{{Field|model=QuestionnaireResponse|section=FormSubmission fields|name=status|type=CharField(255)|notes=One of <code>FormSubmissionStatusChoices</code> (see [[#form-submission-status}}
{{Field|model=QuestionnaireResponse|section=FormSubmission fields|name=response_dump|type=JSONField|notes=<code>default=dict</code>. Raw submitted payload}}
|}

== Enums ==

=== Questionnaire response status ===

<code>QuestionnaireResponseStatusChoices</code> (<code>resources/questionnaire_response/spec.py</code>), <code>str</code> values.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>completed</code>
| The response is finalised (default)
|-
| <code>entered_in_error</code>
| The response was recorded in error
|}

=== Form submission status ===

<code>FormSubmissionStatusChoices</code> (<code>resources/form_submission/spec.py</code>), <code>str</code> values.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Saved but not finalised
|-
| <code>submitted</code>
| Finalised submission
|-
| <code>entered_in_error</code>
| Recorded in error
|}

== Submit payload (nested shapes) ==

Answers go through the questionnaire submit endpoint, whose body is <code>QuestionnaireSubmitRequest</code>. Group questions nest via <code>sub_results</code>, and each answer can carry multiple values:

<syntaxhighlight lang="text">QuestionnaireSubmitRequest {
resource_id: UUID4 # questionnaire being answered
patient: UUID4 (required)
encounter: UUID4 | None
form_submission: UUID4 | None
results: list[QuestionnaireSubmitResult]
}

QuestionnaireSubmitResult {
question_id: UUID4 | UUID5 (required)
body_site: Coding | None
method: Coding | None
taken_at: datetime | None
values: list[QuestionnaireSubmitResultValue]
note: str | None
sub_results: list[list[QuestionnaireSubmitResult]] # nested, for group questions
}

QuestionnaireSubmitResultValue {
value: str | None
unit: Coding | None # for Quantity answers
coding: Coding | None # for coded answers
}</syntaxhighlight>
== Resource specs (API schema) ==

All specs extend <code>EMRResource</code> (<code>resources/base.py</code>).

=== <code>QuestionnaireResponse</code> (<code>resources/questionnaire_response/spec.py</code>) ===

There is no generic create spec — new responses come from the questionnaire submit flow (<code>QuestionnaireSubmitRequest</code>). The update spec carries <code>status</code> only, so the one write you make directly is flagging a response <code>entered_in_error</code>.

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>EMRQuestionnaireResponseBase</code>
| shared
| <code>__model__ = QuestionnaireResponse</code>
|-
| <code>QuestionnaireResponseUpdate</code>
| write · update
| Only <code>status</code> (<code>QuestionnaireResponseStatusChoices</code>, default <code>completed</code>) — used to mark a response <code>entered_in_error</code>
|-
| <code>QuestionnaireResponseReadSpec</code>
| read
| <code>id</code>, <code>status</code>, <code>questionnaire</code> (nested <code>QuestionnaireReadSpec</code>), <code>subject_id</code>, <code>responses</code>, <code>encounter</code> (external id or <code>null</code>), <code>structured_responses</code>, <code>structured_response_type</code>, <code>created_by</code>/<code>updated_by</code> (<code>UserSpec</code>), <code>created_date</code>/<code>modified_date</code>
|}

=== <code>FormSubmission</code> (<code>resources/form_submission/spec.py</code>) ===

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>BaseFormSubmissionSpec</code>
| shared
| <code>__model__ = FormSubmission</code>; <code>id</code> (<code>UUID4?</code>)
|-
| <code>FormSubmissionUpdateSpec</code>
| write · update
| <code>status</code> (<code>FormSubmissionStatusChoices</code>), <code>response_dump</code> (<code>dict</code>)
|-
| <code>FormSubmissionWriteSpec</code>
| write · create
| Adds <code>questionnaire</code> (slug <code>str</code>), <code>patient</code> (<code>UUID4</code>), <code>encounter</code> (<code>UUID4?</code>). <code>perform_extra_deserialization</code> resolves the questionnaire by slug and the patient/encounter by external id; when an encounter is given, the patient is taken from it
|-
| <code>FormSubmissionReadSpec</code>
| read
| <code>status</code>, <code>response_dump</code>, <code>created_date</code>/<code>modified_date</code>, <code>created_by</code>/<code>updated_by</code> (<code>UserSpec?</code>)
|}

== API integration notes ==

* Both map loosely onto the FHIR <code>QuestionnaireResponse</code> resource: <code>responses</code> holds the raw answers, and <code>structured_responses</code> is the extracted, query-friendly form.
* Create a <code>QuestionnaireResponse</code> by submitting a <code>QuestionnaireSubmitRequest</code>. The update spec exists to flag responses <code>entered_in_error</code>.
* <code>FormSubmission</code> runs a draft→submitted lifecycle. Its <code>response_dump</code> is opaque JSON — the questionnaire definition validates it, the model does not.
* The server maintains the audit users (<code>created_by</code>/<code>updated_by</code>); don't set them on write.

{{Related}}

References/Questionnaire Response - Revision history

Admin: Automated edit (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed