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

2026-07-06T04:03:07Z

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

← Older revision		Revision as of 09:33, 6 July 2026
Line 444:		Line 444:
	* On read, the list and detail specs blank out <code>encounter</code>, <code>patient</code>, and <code>questionnaire_response</code>, so don't rely on those being populated in observation payloads.		* On read, the list and detail specs blank out <code>encounter</code>, <code>patient</code>, and <code>questionnaire_response</code>, 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.		* Prefer structured observations. Allergy and medication checks read coded values, not free text, so unstructured data leaves them blind.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:24Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Observation
|order=5
|introduced=3.0
|fhir=Observation
|model=Observation
|reference=References/Base models & conventions
}}

An <code>Observation</code> 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. <code>main_code</code> records ''what'' was observed (usually bound to LOINC) and <code>value</code> holds the result. You rarely create one by hand; most observations are materialized when a questionnaire is submitted.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/observation.py <code>care/emr/models/observation.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/observation/spec.py <code>care/emr/resources/observation/spec.py</code>]
* Value sets: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/observation/valueset.py <code>care/emr/resources/observation/valueset.py</code>]

The model is just storage; several fields are opaque <code>JSONField</code>s. Their real structure lives in the Pydantic resource specs under <code>care/emr/resources/observation/</code>, 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 ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Observation</code>
| A single coded measurement or finding about a patient, captured within an encounter
|}

<code>Observation</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that supplies <code>external_id</code>, <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, <code>created_by</code>/<code>updated_by</code>, and <code>history</code>/<code>meta</code> JSON.

== <code>Observation</code> fields ==

=== Classification & coding ===

{| class="wikitable"
|-
! Field
! Storage type
! Spec shape / notes
|-
| <code>status</code>
| <code>CharField(255)</code>
| Enum <code>ObservationStatus</code> — <code>final</code>, <code>amended</code>, <code>entered_in_error</code>. Required in specs. Questionnaire-sourced observations land as <code>final</code>
|-
| <code>is_group</code>
| <code>BooleanField</code>
| Default <code>False</code>. <code>True</code> marks a grouping/panel observation that holds <code>component</code>/child observations instead of a single value. Not exposed in the resource specs
|-
| <code>category</code>
| <code>JSONField</code> (default <code>{}</code>)
| Spec: optional <code>Coding { system?, version?, code, display? }</code>. FHIR observation category, derived from the questionnaire
|-
| <code>main_code</code>
| <code>JSONField</code> (default <code>{}</code>)
| Spec: optional <code>Coding</code>. What is being observed, typically LOINC (<code>CARE_OBSERVATION_VALUSET</code>, system <code>http://loinc.org</code>)
|-
| <code>alternate_coding</code>
| <code>JSONField</code> (default <code>[]</code>)
| Spec: optional <code>CodeableConcept { id?, coding?: Coding[], text }</code>. Same concept expressed in other code systems
|}

=== Subject & context ===

{| class="wikitable"
|-
! Field
! Storage type
! Spec shape / notes
|-
| <code>subject_type</code>
| <code>CharField(255)</code>
| Enum <code>SubjectType</code> — <code>patient</code>, <code>encounter</code>. Spec defaults to <code>encounter</code>
|-
| <code>subject_id</code>
| <code>UUIDField</code>
| The subject entity's id. Set server-side; not in the spec body
|-
| <code>patient</code>
| <code>FK → Patient</code>
| <code>CASCADE</code>. Set server-side, not in the spec body
|-
| <code>encounter</code>
| <code>FK → Encounter</code>
| <code>CASCADE</code>. Spec field is <code>UUID4 | None</code>. Where the observation was recorded
|-
| <code>effective_datetime</code>
| <code>DateTimeField</code>
| When the observation was effective. Nullable in storage, but the spec requires a tz-aware <code>datetime</code> on create; optional on update
|}

=== Author & performer ===

{| class="wikitable"
|-
! Field
! Storage type
! Spec shape / notes
|-
| <code>data_entered_by</code>
| <code>FK → users.User</code>
| <code>CASCADE</code>, nullable. <code>related_name="observations_entered"</code>. Write specs accept <code>data_entered_by_id: int</code>; read specs serialize a nested <code>UserSpec</code>
|-
| <code>performer</code>
| <code>JSONField</code> (default <code>{}</code>)
| Spec: optional <code>Performer { type: PerformerType (related_person|user), id: str }</code>. Use it when the performer differs from the data-entry user
|}

=== Value ===

{| class="wikitable"
|-
! Field
! Storage type
! Spec shape / notes
|-
| <code>value_type</code>
| <code>CharField(255)</code>
| Enum <code>QuestionType</code> (from the questionnaire module). Tells the client how to read <code>value</code> — see the table below. Required in specs
|-
| <code>value</code>
| <code>JSONField</code>
| Spec: <code>QuestionnaireSubmitResultValue { value?: str, unit?: Coding, coding?: Coding }</code>. Required on create, optional on update. <code>value</code> holds the raw/string result, <code>unit</code> the quantity unit, <code>coding</code> the coded answer
|-
| <code>note</code>
| <code>TextField</code>
| Spec: <code>str | None</code>. Free-text note
|}

=== Clinical qualifiers ===

{| class="wikitable"
|-
! Field
! Storage type
! Spec shape / notes
|-
| <code>body_site</code>
| <code>JSONField</code> (default <code>{}</code>)
| Spec: optional <code>Coding</code> bound to <code>CARE_BODY_SITE_VALUESET</code> (slug <code>system-body-site-observation</code>, SNOMED CT). FHIR <code>Observation.bodySite</code>
|-
| <code>method</code>
| <code>JSONField</code> (default <code>{}</code>)
| Spec: optional <code>Coding</code> bound to <code>CARE_OBSERVATION_COLLECTION_METHOD</code> (slug <code>system-collection-method</code>, SNOMED CT). FHIR <code>Observation.method</code>
|-
| <code>reference_range</code>
| <code>JSONField</code> (default <code>[]</code>)
| Spec: <code>ReferenceRange[]</code> (shape below), default <code>[]</code>. Reference ranges for the value, usually carried over from the observation definition
|-
| <code>interpretation</code>
| <code>JSONField</code> (default <code>{}</code>)
| Spec: free <code>dict</code>, default <code>{}</code>. Coded interpretation against the reference range (high/low/normal). Normal/abnormal/critical value sets exist (below) but are not enforced on this dict
|-
| <code>interpretation_old</code>
| <code>CharField(255)</code>
| Nullable. Legacy free-text interpretation, kept for backward compatibility. Not in the specs
|}

=== Structure & relationships ===

{| class="wikitable"
|-
! Field
! Storage type
! Spec shape / notes
|-
| <code>parent</code>
| <code>UUIDField</code>
| Nullable. Spec: <code>UUID4 | None</code> — the <code>external_id</code> of a parent observation, for nesting related observations
|-
| <code>component</code>
| <code>JSONField</code> (default <code>[]</code>)
| Spec: <code>Component[]</code> (shape below), default <code>[]</code>. Sub-observations sharing this context but carrying their own codes and values (FHIR <code>Observation.component</code>)
|-
| <code>questionnaire_response</code>
| <code>FK → QuestionnaireResponse</code>
| <code>CASCADE</code>, nullable. Spec field is <code>UUID4 | None</code>. The submission that produced this observation
|-
| <code>diagnostic_report</code>
| <code>FK → DiagnosticReport</code>
| <code>CASCADE</code>, nullable. The report this observation belongs to, if any. Not in the write specs
|-
| <code>observation_definition</code>
| <code>FK → ObservationDefinition</code>
| <code>CASCADE</code>, nullable. The definition this observation templates from. Serialized as <code>BaseObservationDefinitionSpec</code> only in <code>ObservationRetrieveSpec</code>
|}

== Enum & value-set reference ==

=== <code>ObservationStatus</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>final</code>
| Recorded, complete and verified. The default for questionnaire-sourced observations
|-
| <code>amended</code>
| Was <code>final</code>, then corrected
|-
| <code>entered_in_error</code>
| Recorded in error; disregard it
|}

=== <code>PerformerType</code> values (<code>performer.type</code>) ===

{| class="wikitable"
|-
! Value
|-
| <code>related_person</code>
|-
| <code>user</code>
|}

=== <code>SubjectType</code> values (<code>subject_type</code>) ===

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

=== <code>QuestionType</code> values (<code>value_type</code>) ===

From the questionnaire module. The value tells the client which key of <code>value</code> to read.

{| class="wikitable"
|-
! Value
! Value sourced from <code>QuestionnaireSubmitResultValue</code>
|-
| <code>group</code>
| grouping node (no direct value)
|-
| <code>boolean</code>
| <code>value</code> (<code>"true"</code>/<code>"false"</code>)
|-
| <code>decimal</code>
| <code>value</code>
|-
| <code>integer</code>
| <code>value</code>
|-
| <code>string</code>
| <code>value</code>
|-
| <code>text</code>
| <code>value</code>
|-
| <code>display</code>
| display-only
|-
| <code>date</code>
| <code>value</code>
|-
| <code>dateTime</code>
| <code>value</code>
|-
| <code>time</code>
| <code>value</code>
|-
| <code>choice</code>
| <code>coding</code>
|-
| <code>url</code>
| <code>value</code>
|-
| <code>quantity</code>
| <code>value</code> + <code>unit</code>
|-
| <code>structured</code>
| structured payload
|}

=== Bound value sets ===

Coded fields validate against registered Care value sets. A <code>body_site</code> or <code>method</code> coding outside its value set is rejected during deserialization.

{| class="wikitable"
|-
! Field
! Value set
! Slug
! System(s)
|-
| <code>main_code</code>
| <code>CARE_OBSERVATION_VALUSET</code>
| <code>system-observation</code>
| <code>http://loinc.org</code>
|-
| <code>body_site</code>
| <code>CARE_BODY_SITE_VALUESET</code>
| <code>system-body-site-observation</code>
| <code>http://snomed.info/sct</code> (curated concept list + descendants of <code>442083009</code>)
|-
| <code>method</code>
| <code>CARE_OBSERVATION_COLLECTION_METHOD</code>
| <code>system-collection-method</code>
| <code>http://snomed.info/sct</code> (descendants of <code>272394005</code>, <code>129264002</code>, <code>386053000</code>)
|}

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

{| class="wikitable"
|-
! Value set
! Slug
! Concepts (system <code>http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation</code>)
|-
| Normal
| <code>system-normal-coded-valueset</code>
| <code>N</code> Normal, <code>ND</code> Not detected, <code>NEG</code> Negative
|-
| Abnormal
| <code>system-abnormal-coded-valueset</code>
| <code>A</code> Abnormal, <code>AA</code> Critically abnormal, <code>H</code> High, <code>HH</code> Critically high, <code>L</code> Low, <code>LL</code> Critically low, <code>POS</code> Positive, <code>DET</code> Detected
|-
| Critical
| <code>system-critical-coded-valueset</code>
| <code>C</code> Critical, <code>CC</code> Critical high, <code>CL</code> Critical low, <code>CV</code> Critical value
|-
| UCUM units
| <code>system-ucum-units</code>
| <code>http://unitsofmeasure.org</code> (all UCUM units)
|}

== Nested JSON shapes (from the spec) ==

The structures behind the model's <code>JSONField</code>s.

=== <code>Coding</code> ===

<syntaxhighlight lang="text">Coding {
system: str | null # e.g. http://loinc.org
version: str | null
code: str # required
display: str | null
} # extra keys forbidden</syntaxhighlight>
=== <code>CodeableConcept</code> (<code>alternate_coding</code>) ===

<syntaxhighlight lang="text">CodeableConcept {
id: str | null
coding: Coding[] | null
text: str | null # field present, required key
} # extra keys forbidden</syntaxhighlight>
=== <code>QuestionnaireSubmitResultValue</code> (<code>value</code>) ===

<syntaxhighlight lang="text">QuestionnaireSubmitResultValue {
value: str | null # raw/string value
unit: Coding | null # for quantity values
coding: Coding | null # for coded values
}</syntaxhighlight>
=== <code>Performer</code> (<code>performer</code>) ===

<syntaxhighlight lang="text">Performer {
type: PerformerType # related_person | user
id: str
}</syntaxhighlight>
=== <code>ReferenceRange</code> (<code>reference_range[]</code>) ===

<syntaxhighlight lang="text">ReferenceRange {
min: float | null
max: float | null
unit: str | null
interpretation: str # required
value: str | null
}</syntaxhighlight>
=== <code>Component</code> (<code>component[]</code>) ===

<syntaxhighlight lang="text">Component {
value: QuestionnaireSubmitResultValue # required
interpretation: str | dict = {}
reference_range: ReferenceRange[] = []
code: Coding | null = null
note: str = ""
}</syntaxhighlight>
== Resource specs (API schema) ==

The Pydantic specs build on [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>EMRResource</code>], which provides <code>serialize</code> / <code>de_serialize</code> and the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. Every concrete spec inherits from <code>BaseObservationSpec</code>.

{| class="wikitable"
|-
! Spec
! Role
! Notes
|-
| <code>BaseObservationSpec</code>
| shared base
| Defines the common fields: <code>id</code>, <code>status</code>, <code>category</code>, <code>main_code</code>, <code>alternate_coding</code>, <code>subject_type</code>, <code>encounter</code>, <code>effective_datetime</code>, <code>performer</code>, <code>value_type</code>, <code>value</code>, <code>note</code>, <code>body_site</code> (bound), <code>method</code> (bound), <code>reference_range</code>, <code>interpretation</code>, <code>parent</code>, <code>questionnaire_response</code>, <code>component</code>
|-
| <code>ObservationSpec</code>
| write · create
| Adds <code>data_entered_by_id</code>, <code>created_by_id</code>, <code>updated_by_id</code> (all <code>int</code>). Used internally when materializing observations from a questionnaire submission
|-
| <code>ObservationUpdateSpec</code>
| write · update
| The base, but <code>effective_datetime</code> and <code>value</code> relax to optional (<code>None</code>) for partial updates
|-
| <code>ObservationReadSpec</code>
| read · list
| Swaps the user IDs for nested <code>created_by</code> / <code>updated_by</code> / <code>data_entered_by</code> <code>UserSpec</code> objects
|-
| <code>ObservationRetrieveSpec</code>
| read · detail
| Extends <code>ObservationReadSpec</code> and additionally serializes <code>observation_definition</code> via <code>BaseObservationDefinitionSpec</code> when it is set
|}

=== Server-side behaviour ===

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

== Related models ==

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

<syntaxhighlight lang="text">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)</syntaxhighlight>
<code>parent</code> is the exception: a soft, UUID-based self-reference to another observation's <code>external_id</code>, not a Django FK. It lets observations nest without a database constraint.

== API integration notes ==

* Observations are exposed through Care's REST API and align with the FHIR <code>Observation</code> resource. FHIR field names (<code>effectiveDateTime</code>, <code>bodySite</code>, 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. <code>value</code> and <code>value_type</code> mirror the submission types (<code>QuestionnaireSubmitResultValue</code> / <code>QuestionType</code>), and <code>questionnaire_response</code> records provenance.
* <code>effective_datetime</code> must be timezone-aware. Required on create, optional on update.
* <code>status</code> is one of <code>final</code> / <code>amended</code> / <code>entered_in_error</code>; questionnaire-sourced observations are <code>final</code>.
* <code>body_site</code> and <code>method</code> are validated against their bound value sets, and <code>main_code</code> is expected to bind to LOINC via <code>CARE_OBSERVATION_VALUSET</code>.
* On read, the list and detail specs blank out <code>encounter</code>, <code>patient</code>, and <code>questionnaire_response</code>, 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}}

References/Observation - Revision history

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

Admin: OHC identity seed