Clinical care

Questionnaire

A Questionnaire 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…

3.1 · versioned documentation · 12 min read

A Questionnaire 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 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 care/emr/resources/questionnaire*: enums, the nested shape of the JSON fields, validation, and the split between read and write contracts.

Source (model): care/emr/models/questionnaire.py

Source (specs): resources/questionnaire/spec.py · resources/questionnaire/utils.py · resources/questionnaire/questionnaire_organization.py · resources/questionnaire_response/spec.py · resources/questionnaire_response_template/spec.py · resources/form_submission/spec.py

Models

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

All extend EMRBaseModel, which supplies external_id, audit fields, and soft-delete semantics.

Questionnaire fields

Definition

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

Organization scope caches

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

Enum values

QuestionnaireStatus values

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

SubjectType values

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

QuestionType values

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

EnableOperator values

The comparison for an enable_when condition (EnableWhen.operator).

EnableBehavior values

How multiple enable_when conditions combine (Question.enable_behavior).

DisabledDisplay values

How a disabled question renders (Question.disabled_display).

AnswerConstraint values

Whether free input outside the options is allowed (Question.answer_constraint).

QuestionnaireResponseStatusChoices values

QuestionnaireResponse.status (model default "completed").

FormSubmissionStatusChoices values

FormSubmission.status.

Question nested shape

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

A model_validator (mode after) enforces three rules:

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

Sub-specs of Question

Resource specs (API schema)

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

Questionnaire

Value sets bound on questions: code → system-observation (LOINC), unit → system-ucum-units (UCUM). answer_value_set references any ValueSet by slug.

Questionnaire response

Submit request schema (not a DB write spec)

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

Form submission

Questionnaire response template

template_data (TemplateData) shape

QuestionnaireResponseTemplate.template_data is an opaque JSONField that the spec validates as:

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

Related models

FormSubmission

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

questionnaire → FK Questionnaire (CASCADE)
patient       → FK emr.Patient (CASCADE)
encounter     → FK emr.Encounter (CASCADE, nullable)
status        → CharField(255)         # FormSubmissionStatusChoices
response_dump → JSONField (default {})

QuestionnaireResponse

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

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"

QuestionnaireOrganization / QuestionnaireFacilityOrganization

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

questionnaire → FK Questionnaire (CASCADE)
organization  → FK Organization | FacilityOrganization (CASCADE)

Each overrides save() to recompute the matching cache on the parent Questionnaire (see Methods & save behaviour). Their specs (questionnaire_organization.py) exclude both FKs from serialization (__exclude__ = ["questionnaire", "organization"]): the write spec accepts organization: UUID4, the read spec returns organization: dict.

QuestionnaireResponseTemplate

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

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

Methods & save behaviour

Questionnaire.get_questions_by_id()

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

QuestionnaireResponse.render_responses()

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

Submission handling — handle_response()

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

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

Organization cache sync

QuestionnaireOrganization.save() and QuestionnaireFacilityOrganization.save() call super().save(), then sync_questionnaire_cache(), which:

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

Saving any organization link triggers a second write to the Questionnaire row.

API integration notes

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

Related

• Source: questionnaire.py on GitHub
• Spec: questionnaire/spec.py · response spec · submit utils · form_submission spec · response template spec
• Reference: Base model
• Reference: Questionnaire Response — submitted answers (QuestionnaireResponse / FormSubmission)
• Reference: Questionnaire Response Template — reusable pre-fill templates
• Reference: ValueSet
• Reference: Patient
• Reference: Encounter
• Reference: Observation
• Reference: Organization
• Reference: MedicationRequest
• Reference: ServiceRequest
• Reference: ActivityDefinition

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/definitions/questionnaire.mdx:1 · f6e9f05f