Clinical care

Observation

An Observation is one named, coded data point about a subject — almost always a patient: a blood pressure reading, a temperature, a coded answer captured through a questionnaire. main_code records what was observed and value holds the result.…

3.1 · versioned documentation · 9 min read

An Observation is one named, coded data point about a subject — almost always a patient: a blood pressure reading, a temperature, a coded answer captured through a questionnaire. main_code records what was observed (usually bound to LOINC) and value holds the result. You rarely create one by hand; most observations are materialized when a questionnaire is submitted.

Source:

• Model: care/emr/models/observation.py
• Resource spec: care/emr/resources/observation/spec.py
• Value sets: care/emr/resources/observation/valueset.py

The model is just storage; several fields are opaque JSONFields. Their real structure lives in the Pydantic resource specs under care/emr/resources/observation/, which own the enums, nested JSON shapes, validation, and the read/write schema split. Each field row below gives the storage column first, then the shape the spec enforces on top of it.

Models

Observation extends EMRBaseModel, the shared MANSOQ EMR base that supplies external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and history/meta JSON.

Observation fields

Classification & coding

Subject & context

Author & performer

Value

Clinical qualifiers

Structure & relationships

Enum & value-set reference

ObservationStatus values

PerformerType values (performer.type)

SubjectType values (subject_type)

QuestionType values (value_type)

From the questionnaire module. The value tells the client which key of value to read.

Bound value sets

Coded fields validate against registered MANSOQ value sets. A body_site or method coding outside its value set is rejected during deserialization.

These interpretation value sets are registered for the frontend and observation definitions, but are not enforced on the interpretation dict:

Nested JSON shapes (from the spec)

The structures behind the model's JSONFields.

Coding

Coding {
  system:  str | null      # e.g. http://loinc.org
  version: str | null
  code:    str             # required
  display: str | null
}                          # extra keys forbidden

CodeableConcept (alternate_coding)

CodeableConcept {
  id:     str | null
  coding: Coding[] | null
  text:   str | null       # field present, required key
}                          # extra keys forbidden

QuestionnaireSubmitResultValue (value)

QuestionnaireSubmitResultValue {
  value:  str | null       # raw/string value
  unit:   Coding | null    # for quantity values
  coding: Coding | null    # for coded values
}

Performer (performer)

Performer {
  type: PerformerType      # related_person | user
  id:   str
}

ReferenceRange (reference_range[])

ReferenceRange {
  min:            float | null
  max:            float | null
  unit:           str | null
  interpretation: str        # required
  value:          str | null
}

Component (component[])

Component {
  value:           QuestionnaireSubmitResultValue   # required
  interpretation:  str | dict     = {}
  reference_range: ReferenceRange[] = []
  code:            Coding | null   = null
  note:            str            = ""
}

Resource specs (API schema)

The Pydantic specs build on EMRResource, which provides serialize / de_serialize and the perform_extra_serialization / perform_extra_deserialization hooks. Every concrete spec inherits from BaseObservationSpec.

Server-side behaviour

• ObservationSpec.perform_extra_deserialization (create/update): sets obj.external_id = self.id, copies data_entered_by_id, created_by_id, updated_by_id onto the model, drops data_entered_by_id from meta, and on create (is_update is false) clears obj.id so a new row is inserted.
• ObservationReadSpec.perform_extra_serialization: maps id from external_id; deliberately blanks encounter, patient, and questionnaire_response to None in the output to avoid extra DB queries; resolves the audit users (created_by, updated_by) and data_entered_by from cache (model_from_cache).
• ObservationRetrieveSpec.perform_extra_serialization: calls the parent, then inlines the full observation_definition when the FK is set.
• body_site / method are ValueSetBoundCoding[...]: the supplied Coding is validated against its bound value set during deserialization and rejected if the code is not a member.
• de_serialize only writes fields present in the model's column mapping. Non-default values are persisted (model_dump(exclude_defaults=True)), and unknown spec-only fields would land in meta when __store_metadata__ is set — which, by default, it is not for observations.

Related models

Observation is self-contained; it expresses relationships through foreign keys rather than secondary tables.

patient                → FK Patient (CASCADE)
encounter              → FK Encounter (CASCADE)
data_entered_by        → FK users.User (CASCADE, nullable)
questionnaire_response → FK QuestionnaireResponse (CASCADE, nullable)
diagnostic_report      → FK DiagnosticReport (CASCADE, nullable)
observation_definition → FK ObservationDefinition (CASCADE, nullable)

parent is the exception: a soft, UUID-based self-reference to another observation's external_id, not a Django FK. It lets observations nest without a database constraint.

API integration notes

• Observations are exposed through MANSOQ's REST API and align with the FHIR Observation resource. FHIR field names (effectiveDateTime, bodySite, and so on) differ from the Django model names; the resource specs above are the authoritative request/response schemas.
• Most observations are created as a side effect of submitting a questionnaire. value and value_type mirror the submission types (QuestionnaireSubmitResultValue / QuestionType), and questionnaire_response records provenance.
• effective_datetime must be timezone-aware. Required on create, optional on update.
• status is one of final / amended / entered_in_error; questionnaire-sourced observations are final.
• body_site and method are validated against their bound value sets, and main_code is expected to bind to LOINC via MANSOQ_OBSERVATION_VALUSET.
• On read, the list and detail specs blank out encounter, patient, and questionnaire_response, so don't rely on those being populated in observation payloads.
• Prefer structured observations. Allergy and medication checks read coded values, not free text, so unstructured data leaves them blind.

Related

• Reference: Observation Definition
• Reference: Diagnostic Report
• Reference: Questionnaire
• Reference: Encounter
• Reference: Patient
• Reference: Base Model
• Source: observation.py on GitHub
• Source: observation/spec.py on GitHub
• Source: observation/valueset.py on GitHub
• Source: resources/base.py on GitHub

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/clinical/observation.mdx:1 · f6e9f05f