Admin: OHC identity seed

2026-07-04T22:44:49Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Questionnaire
|order=1
|introduced=3.0
|model=Questionnaire
|reference=References/Activity Definition
}}

A <code>Questionnaire</code> is a versioned, FHIR-inspired form: a tree of questions answered about a patient or an encounter. You touch it whenever you define a data-collection form, render one for filling, or submit answers — which can flow back out as [[References/Observation|Observations]]. It captures both clinical data and arbitrary non-clinical structured data.

The Django model is only the storage layer. The API schema you code against lives in the Pydantic resource specs under <code>care/emr/resources/questionnaire*</code>: enums, the nested shape of the JSON fields, validation, and the split between read and write contracts.

'''Source (model):''' [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/questionnaire.py <code>care/emr/models/questionnaire.py</code>]

'''Source (specs):''' [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/questionnaire/spec.py <code>resources/questionnaire/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/questionnaire/utils.py <code>resources/questionnaire/utils.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/questionnaire/questionnaire_organization.py <code>resources/questionnaire/questionnaire_organization.py</code>] · [<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/questionnaire_response_template/spec.py <code>resources/questionnaire_response_template/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 ==

Six models back the forms feature. The <code>Questionnaire</code> is the definition; everything else records submissions, answers, organization scope, or reusable prefill.

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Questionnaire</code>
| A versioned form definition: questions, styling, subject type, and status
|-
| <code>FormSubmission</code>
| A submission of a questionnaire against a patient (and optional encounter)
|-
| <code>QuestionnaireResponse</code>
| A stored set of answers for a subject, optionally tied to a submission
|-
| <code>QuestionnaireOrganization</code>
| Scopes a questionnaire to an instance-level <code>Organization</code>
|-
| <code>QuestionnaireFacilityOrganization</code>
| Scopes a questionnaire to a <code>FacilityOrganization</code>
|-
| <code>QuestionnaireResponseTemplate</code>
| Reusable prefill template for questionnaire responses
|}

All extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], which supplies <code>external_id</code>, audit fields, and soft-delete semantics.

== <code>Questionnaire</code> fields ==

=== Definition ===

{| class="wikitable"
|-
! Field
! Type
! Req
! Notes
{{Field|model=Questionnaire|section=Definition|name=version|type=CharField(255)|notes=yes}}
{{Field|model=Questionnaire|section=Definition|name=slug|type=CharField(255)|notes=yes}}
{{Field|model=Questionnaire|section=Definition|name=title|type=CharField(255)|notes=yes}}
{{Field|model=Questionnaire|section=Definition|name=description|type=TextField|notes=no}}
{{Field|model=Questionnaire|section=Definition|name=subject_type|type=CharField(255)|notes=yes}}
{{Field|model=Questionnaire|section=Definition|name=status|type=CharField(255)|notes=yes}}
{{Field|model=Questionnaire|section=Definition|name=styling_metadata|type=JSONField|notes=no}}
{{Field|model=Questionnaire|section=Definition|name=questions|type=JSONField|notes=yes}}
{{Field|model=Questionnaire|section=Definition|name=organization_cache|type=ArrayField[int]|notes=—}}
{{Field|model=Questionnaire|section=Definition|name=internal_organization_cache|type=ArrayField[int]|notes=—}}
|}

The write spec also carries a <code>type: str</code> field (default <code>"custom"</code>) that has no backing model column.

==== Organization scope caches ====

<code>organization_cache</code> and <code>internal_organization_cache</code> hold flattened organization IDs so access filtering can run without deep joins. The through-models below own them; clients never write them directly.

{| class="wikitable"
|-
! Field
! Maintained by
|-
| <code>organization_cache</code>
| <code>QuestionnaireOrganization.sync_questionnaire_cache()</code> — instance <code>Organization</code> IDs plus each org's <code>parent_cache</code>
|-
| <code>internal_organization_cache</code>
| <code>QuestionnaireFacilityOrganization.sync_questionnaire_cache()</code> — <code>FacilityOrganization</code> IDs plus each org's <code>parent_cache</code>
|}

== Enum values ==

=== <code>QuestionnaireStatus</code> values ===

The lifecycle state of the definition, modeled on FHIR publication-status. Once a questionnaire is <code>active</code>, edit and delete are off the table — move it to <code>retired</code> instead.

{| class="wikitable"
|-
! Value
|-
| <code>active</code>
|-
| <code>retired</code>
|-
| <code>draft</code>
|}

=== <code>SubjectType</code> values ===

What kind of resource the form is about. This drives whether an encounter is required at submit time.

{| class="wikitable"
|-
! Value
|-
| <code>patient</code>
|-
| <code>encounter</code>
|}

=== <code>QuestionType</code> values ===

The <code>type</code> of each question (<code>Question.type</code>). The commented-out members <code>open_choice</code>, <code>attachment</code>, and <code>reference</code> are not implemented.

{| class="wikitable"
|-
! Value
! Notes
|-
| <code>group</code>
| Container; must have ≥1 sub-question
|-
| <code>boolean</code>
| Validated against <code>true/false/1/0</code> on submit
|-
| <code>decimal</code>
|
|-
| <code>integer</code>
|
|-
| <code>string</code>
|
|-
| <code>text</code>
| Length capped by <code>settings.MAX_QUESTIONNAIRE_TEXT_RESPONSE_SIZE</code> on submit
|-
| <code>display</code>
| Display-only, no answer
|-
| <code>date</code>
| ISO date
|-
| <code>dateTime</code>
| Must include timezone on submit
|-
| <code>time</code>
| <code>%H:%M:%S</code>
|-
| <code>choice</code>
| Requires <code>answer_option</code> or <code>answer_value_set</code>
|-
| <code>url</code>
| Must have scheme + netloc
|-
| <code>quantity</code>
| Requires <code>answer_option</code> or <code>answer_value_set</code>; answers need a <code>unit</code>
|-
| <code>structured</code>
| Skipped by response validation
|}

=== <code>EnableOperator</code> values ===

The comparison for an <code>enable_when</code> condition (<code>EnableWhen.operator</code>).

{| class="wikitable"
|-
! Value
|-
| <code>exists</code>
|-
| <code>equals</code>
|-
| <code>not_equals</code>
|-
| <code>greater</code>
|-
| <code>less</code>
|-
| <code>greater_or_equals</code>
|-
| <code>less_or_equals</code>
|}

=== <code>EnableBehavior</code> values ===

How multiple <code>enable_when</code> conditions combine (<code>Question.enable_behavior</code>).

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>all</code>
| Enable only if all conditions pass (default on submit)
|-
| <code>any</code>
| Enable if any condition passes
|}

=== <code>DisabledDisplay</code> values ===

How a disabled question renders (<code>Question.disabled_display</code>).

{| class="wikitable"
|-
! Value
|-
| <code>hidden</code>
|-
| <code>protected</code>
|}

=== <code>AnswerConstraint</code> values ===

Whether free input outside the options is allowed (<code>Question.answer_constraint</code>).

{| class="wikitable"
|-
! Value
|-
| <code>required</code>
|-
| <code>optional</code>
|}

=== <code>QuestionnaireResponseStatusChoices</code> values ===

<code>QuestionnaireResponse.status</code> (model default <code>"completed"</code>).

{| class="wikitable"
|-
! Value
|-
| <code>completed</code>
|-
| <code>entered_in_error</code>
|}

=== <code>FormSubmissionStatusChoices</code> values ===

<code>FormSubmission.status</code>.

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>submitted</code>
|-
| <code>entered_in_error</code>
|}

== <code>Question</code> nested shape ==

<code>Questionnaire.questions</code> is an opaque <code>JSONField</code>, but the API contract is a recursive list of <code>Question</code> (<code>QuestionnaireBaseSpec</code>). Fields, with their real types and validation:

{| class="wikitable"
|-
! Field
! Type
! Req
! Default
! Notes
{{Field|model=Questionnaire|section=Question nested shape|name=link_id|type=str|notes=yes}}
{{Field|model=Questionnaire|section=Question nested shape|name=id|type=UUID4 | UUID5|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=code|type=Coding bound to value set system-observation|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=collect_time|type=bool|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=collect_performer|type=bool|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=text|type=str|notes=yes}}
{{Field|model=Questionnaire|section=Question nested shape|name=description|type=str | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=type|type=QuestionType|notes=yes}}
{{Field|model=Questionnaire|section=Question nested shape|name=structured_type|type=str | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=enable_when|type=list[EnableWhen] | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=enable_behavior|type=EnableBehavior | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=disabled_display|type=DisabledDisplay | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=collect_body_site|type=bool | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=collect_method|type=bool | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=required|type=bool | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=repeats|type=bool | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=read_only|type=bool | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=max_length|type=int | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=answer_constraint|type=AnswerConstraint | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=answer_option|type=list[AnswerOption] | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=answer_value_set|type=str | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=is_observation|type=bool | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=unit|type=Coding bound to value set system-ucum-units|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=questions|type=list[Question]|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=formula|type=str | None|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=styling_metadata|type=dict|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=templates|type=list[TemplateConfig]|notes=no}}
{{Field|model=Questionnaire|section=Question nested shape|name=is_component|type=bool|notes=no}}
|}

A <code>model_validator</code> (mode <code>after</code>) enforces three rules:

* <code>choice</code> / <code>quantity</code> types must have <code>answer_option</code> or <code>answer_value_set</code>.
* <code>group</code> types must have at least one sub-question.
* <code>answer_value_set</code>, when set, must reference an existing <code>ValueSet</code>.

=== Sub-specs of <code>Question</code> ===

{| class="wikitable"
|-
! Spec
! Shape
|-
| <code>EnableWhen</code>
| <code>{ question: str (link_id), operator: EnableOperator, answer: Any }</code>
|-
| <code>AnswerOption</code>
| <code>{ value: Any (non-blank, stripped), initial_selected: bool = false }</code>
|-
| <code>Performer</code>
| <code>{ performer_type: str, performer_id: str | None, text: str | None }</code>
|-
| <code>TemplateConfig</code>
| <code>{ name: str, content: str, structured_content: dict | None, meta: dict | None }</code>
|}

== Resource specs (API schema) ==

Every spec builds on <code>EMRResource</code>, which provides <code>serialize</code> / <code>de_serialize</code>. Read specs run <code>perform_extra_serialization</code>; write specs run <code>perform_extra_deserialization</code>.

=== Questionnaire ===

{| class="wikitable"
|-
! Spec
! Role
! Key fields / behaviour
|-
| <code>QuestionnaireBaseSpec</code>
| shared
| <code>__model__ = Questionnaire</code>
|-
| <code>QuestionnaireWriteSpec</code>
| write (base)
| <code>version</code> (frozen <code>"1.0"</code>), <code>slug</code> (<code>SlugType</code>), <code>title</code>, <code>description</code>, <code>type</code> (<code>"custom"</code>), <code>status</code>, <code>subject_type</code>, <code>styling_metadata</code>, <code>questions</code>. Validates slug uniqueness and that it doesn't shadow internal types, a non-empty title, and unique <code>link_id</code>s and <code>id</code>s across the whole tree
|-
| <code>QuestionnaireSpec</code>
| write · create
| Extends the write spec with <code>organizations: list[UUID4]</code> (<code>min_length=1</code>). <code>perform_extra_deserialization</code> stashes them on <code>obj._organizations</code>; the view then links them through <code>QuestionnaireOrganization</code>, which rebuilds <code>organization_cache</code>
|-
| <code>QuestionnaireUpdateSpec</code>
| write · update
| Same as <code>QuestionnaireWriteSpec</code>, minus <code>organizations</code>
|-
| <code>QuestionnaireReadSpec</code>
| read · list/detail
| <code>id</code> (= <code>external_id</code>), <code>slug</code>, <code>version</code>, <code>title</code>, <code>description</code>, <code>status</code>, <code>subject_type</code>, <code>styling_metadata</code>, <code>questions</code> (raw list), <code>created_by</code> / <code>updated_by</code> (resolved via <code>serialize_audit_users</code>)
|}

Value sets bound on questions: <code>code</code> → <code>system-observation</code> (LOINC), <code>unit</code> → <code>system-ucum-units</code> (UCUM). <code>answer_value_set</code> references any [[References/Value Set|<code>ValueSet</code>]] by slug.

=== Questionnaire response ===

{| class="wikitable"
|-
! Spec
! Role
! Key fields / behaviour
|-
| <code>EMRQuestionnaireResponseBase</code>
| shared
| <code>__model__ = QuestionnaireResponse</code>
|-
| <code>QuestionnaireResponseUpdate</code>
| write · update
| <code>status: QuestionnaireResponseStatusChoices</code> (default <code>completed</code>) — the only handle for voiding a response by marking it <code>entered_in_error</code>
|-
| <code>QuestionnaireResponseReadSpec</code>
| read · detail
| <code>id</code>, <code>status</code>, <code>questionnaire</code> (nested <code>QuestionnaireReadSpec</code>), <code>subject_id</code>, <code>responses</code> (raw list), <code>encounter</code> (external id or <code>None</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>
|}

==== Submit request schema (not a DB write spec) ====

The submit endpoint (<code>/questionnaire/<slug>/submit/</code>) takes a plain Pydantic request, which <code>handle_response()</code> in <code>utils.py</code> validates and persists:

{| class="wikitable"
|-
! Spec
! Shape
|-
| <code>QuestionnaireSubmitRequest</code>
| <code>{ resource_id: UUID4, encounter: UUID4 | None, patient: UUID4, results: list[QuestionnaireSubmitResult], form_submission: UUID4 | None }</code>
|-
| <code>QuestionnaireSubmitResult</code>
| <code>{ question_id: UUID4|UUID5, body_site: Coding | None, method: Coding | None, taken_at: datetime | None, values: list[QuestionnaireSubmitResultValue], note: str | None, sub_results: list[list[QuestionnaireSubmitResult]] }</code>
|-
| <code>QuestionnaireSubmitResultValue</code>
| <code>{ value: str | None, unit: Coding | None, coding: Coding | None }</code>
|}

=== Form submission ===

{| class="wikitable"
|-
! Spec
! Role
! Key fields / behaviour
|-
| <code>BaseFormSubmissionSpec</code>
| shared
| <code>__model__ = FormSubmission</code>, <code>id: UUID4 | None</code>
|-
| <code>FormSubmissionUpdateSpec</code>
| write · update
| <code>status: FormSubmissionStatusChoices</code>, <code>response_dump: dict</code>
|-
| <code>FormSubmissionWriteSpec</code>
| write · create
| Adds <code>questionnaire: str</code> (slug), <code>patient: UUID4</code>, <code>encounter: UUID4 | None</code>. <code>perform_extra_deserialization</code> resolves the questionnaire by slug and the patient/encounter by <code>external_id</code>; when an encounter is given it overrides <code>patient</code> with the encounter's patient
|-
| <code>FormSubmissionReadSpec</code>
| read · detail
| <code>id</code>, <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>)
|}

=== Questionnaire response template ===

{| class="wikitable"
|-
! Spec
! Role
! Key fields / behaviour
|-
| <code>QuestionnaireResponseTemplateBaseSpec</code>
| shared
| <code>__model__ = QuestionnaireResponseTemplate</code>, <code>id: UUID4 | None</code>, <code>template_data: TemplateData</code>, <code>name: str</code>, <code>description: str = ""</code>
|-
| <code>QuestionnaireResponseTemplateCreateSpec</code>
| write · create
| Adds <code>questionnaire: str | None</code> (slug), <code>facility: UUID4 | None</code>, <code>users: list[str]</code>, <code>facility_organizations: list[UUID4]</code>. Requires <code>facility</code> whenever <code>facility_organizations</code> is set. Resolves questionnaire/facility and recomputes <code>available_keys</code> from the non-empty keys of <code>template_data</code>
|-
| <code>QuestionnaireResponseTemplateUpdateSpec</code>
| write · update
| <code>users</code>, <code>facility_organizations</code>; recomputes <code>available_keys</code>
|-
| <code>QuestionnaireResponseTemplateReadSpec</code>
| read · list
| <code>created_date</code>, <code>modified_date</code>; <code>id</code> = <code>external_id</code>
|-
| <code>QuestionnaireResponseTemplateRetrieveSpec</code>
| read · detail
| Extends the read spec with resolved <code>users: list[dict]</code>, <code>facility_organizations: list[dict]</code>, <code>created_by</code>, <code>updated_by</code>
|}

==== <code>template_data</code> (<code>TemplateData</code>) shape ====

<code>QuestionnaireResponseTemplate.template_data</code> is an opaque <code>JSONField</code> that the spec validates as:

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Questionnaire|section=template_data (TemplateData) shape|name=medication_request|type=list[MedicationRequestTemplateSpec] | None|notes=Extends the [[References/Medication Request}}
{{Field|model=Questionnaire|section=template_data (TemplateData) shape|name=questionnaire|type=list[QuestionnaireAnswer] | None|notes=<code>QuestionnaireAnswer = { question_id: str, answer: dict, meta: dict }</code>}}
{{Field|model=Questionnaire|section=template_data (TemplateData) shape|name=activity_definition|type=list[ActivityDefinitionTemplateSpec] | None|notes=<code>{ slug (validated against ActivityDefinition), service_request: ServiceRequestUpdateSpec }</code>}}
{{Field|model=Questionnaire|section=template_data (TemplateData) shape|name=meta|type=dict | None|notes=}}
|}

<code>available_keys</code> (model <code>ArrayField</code>) is server-maintained: on create/update it is set to the <code>template_data</code> keys whose value is truthy.

== Related models ==

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

A submission event linking a questionnaire to a patient and, optionally, an encounter.

<syntaxhighlight lang="text">questionnaire → FK Questionnaire (CASCADE)
patient → FK emr.Patient (CASCADE)
encounter → FK emr.Encounter (CASCADE, nullable)
status → CharField(255) # FormSubmissionStatusChoices
response_dump → JSONField (default {})</syntaxhighlight>
=== <code>QuestionnaireResponse</code> ===

The answers for a subject. The <code>questionnaire</code> FK is nullable, so a response can outlive or detach from its definition.

<syntaxhighlight lang="text">questionnaire → FK Questionnaire (CASCADE, nullable)
subject_id → UUIDField
responses → JSONField (default []) # raw submitted results
structured_responses → JSONField (default {}) # extracted/structured data
structured_response_type → CharField (nullable)
patient → FK emr.Patient (CASCADE)
encounter → FK emr.Encounter (CASCADE, nullable)
form_submission → FK FormSubmission (CASCADE, nullable)
status → CharField(255), default "completed"</syntaxhighlight>
=== <code>QuestionnaireOrganization</code> / <code>QuestionnaireFacilityOrganization</code> ===

Through-models that scope a questionnaire to organizations — the first to an instance-level <code>Organization</code>, the second to a <code>FacilityOrganization</code>.

<syntaxhighlight lang="text">questionnaire → FK Questionnaire (CASCADE)
organization → FK Organization | FacilityOrganization (CASCADE)</syntaxhighlight>
Each overrides <code>save()</code> to recompute the matching cache on the parent <code>Questionnaire</code> (see [[#organization-cache-sync|Methods & save behaviour]]). Their specs (<code>questionnaire_organization.py</code>) exclude both FKs from serialization (<code>__exclude__ = ["questionnaire", "organization"]</code>): the write spec accepts <code>organization: UUID4</code>, the read spec returns <code>organization: dict</code>.

=== <code>QuestionnaireResponseTemplate</code> ===

A reusable template that prefills questionnaire responses, optionally scoped to a facility and to specific facility organizations or users.

<syntaxhighlight lang="text">facility → FK facility.Facility (CASCADE, nullable)
name → CharField(255)
description → TextField (default "")
template_data → JSONField (default {}) # TemplateData shape
questionnaire → FK Questionnaire (CASCADE, nullable, default None)
facility_organizations → ArrayField[int] (default [])
users → ArrayField[int] (default [])
available_keys → ArrayField[CharField(255)] (default []) # server-maintained</syntaxhighlight>
== Methods & save behaviour ==

=== <code>Questionnaire.get_questions_by_id()</code> ===

Walks the <code>questions</code> tree, recursing into nested <code>questions</code>, and returns a <code>{ str(question_id): question }</code> dict. The result is memoized on the instance via <code>_questions_by_id_cache</code>. If <code>questions</code> is not a list, it returns an empty dict.

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

Joins stored <code>responses</code> against the live questionnaire definition. For each answer it looks up the question through <code>questionnaire.get_questions_by_id()</code> and returns a list of <code>{ "answer": ..., "question": ... }</code>. It returns an empty list when there are no responses or no linked questionnaire, and skips any answer whose <code>question_id</code> is no longer in the definition.

=== Submission handling — <code>handle_response()</code> ===

<code>resources/questionnaire/utils.py</code> runs this server-side on every submission:

# Rejects the submission if the questionnaire <code>status != "active"</code> (<code>questionnaire_inactive</code>).
# Resolves <code>encounter</code> (required when <code>subject_type == "encounter"</code>) and <code>patient</code> by <code>external_id</code>.
# Rejects empty submissions (<code>questionnaire_empty</code>).
# Prunes the question tree by <code>enable_when</code> rules; answers to disabled questions raise <code>enable_when_failed</code>.
# Validates each answer against its <code>type</code> (type checks per [[#questiontype-values|QuestionType]]), <code>required</code>, <code>answer_value_set</code> (the coding must belong to the value set), and <code>quantity</code> units. Any failure aborts with an <code>errors</code> payload.
# Builds <code>ObservationSpec</code> objects for coded/group questions and creates a <code>QuestionnaireResponse</code> (raw <code>responses</code> = the dumped results).
# When an encounter is present, bulk-creates the derived [[References/Observation|Observations]], linked back to the response.

=== Organization cache sync ===

<code>QuestionnaireOrganization.save()</code> and <code>QuestionnaireFacilityOrganization.save()</code> call <code>super().save()</code>, then <code>sync_questionnaire_cache()</code>, which:

# Loads all through-rows for the parent questionnaire.
# Collects each linked organization's <code>id</code> plus its <code>parent_cache</code> (ancestor chain).
# De-duplicates the IDs.
# Writes them back via <code>questionnaire.save(update_fields=[...])</code> — <code>organization_cache</code> for instance orgs, <code>internal_organization_cache</code> for facility orgs.

Saving any organization link triggers a second write to the <code>Questionnaire</code> row.

== API integration notes ==

* Questionnaires expose CRUD plus a submit endpoint (<code>/questionnaire/<slug>/submit/</code>). Create uses <code>QuestionnaireSpec</code> (requires ≥1 <code>organizations</code>); update uses <code>QuestionnaireUpdateSpec</code>; reads use <code>QuestionnaireReadSpec</code>.
* <code>questions</code> and <code>styling_metadata</code> are open <code>JSONField</code>s at the DB layer, but the API validates <code>questions</code> against the recursive [[#question-nested-shape|<code>Question</code>]] spec — unique <code>link_id</code>/<code>id</code>, the choice/quantity/group constraints, and value-set existence. <code>styling_metadata</code> is never validated.
* <code>organization_cache</code> / <code>internal_organization_cache</code> and <code>QuestionnaireResponseTemplate.available_keys</code> are platform-maintained. Don't set them from clients; write through the through-models or <code>template_data</code>.
* Submitting answers validates type/required/value-set server-side and, for clinical questions, materializes [[References/Observation|Observations]]. To void a response, set its status to <code>entered_in_error</code> via <code>QuestionnaireResponseUpdate</code>.
* <code>FormSubmissionWriteSpec</code> resolves the questionnaire by slug and, when an encounter is supplied, forces the submission's patient to the encounter's patient.

{{Related}}

References/Questionnaire - Revision history

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

Admin: OHC identity seed