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

2026-07-06T04:02:07Z

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

← Older revision		Revision as of 09:32, 6 July 2026
Line 269:		Line 269:
	* <code>onset</code> and <code>abatement</code> are structured choice-of-type objects (<code>_datetime</code>, <code>_age</code>, <code>*_string</code>, <code>note</code>), not arbitrary JSON. <code>onset_datetime</code> must be timezone-aware and not in the future.		* <code>onset</code> and <code>abatement</code> are structured choice-of-type objects (<code>_datetime</code>, <code>_age</code>, <code>*_string</code>, <code>note</code>), not arbitrary JSON. <code>onset_datetime</code> must be timezone-aware and not in the future.
	* Don't send <code>patient</code>, <code>external_id</code>, audit fields, or <code>deleted</code> from the client — the server owns them.		* Don't send <code>patient</code>, <code>external_id</code>, audit fields, or <code>deleted</code> from the client — the server owns them.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:17Z

OHC identity seed

New page

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

A <code>Condition</code> records a clinical problem, diagnosis, or symptom against a patient. It maps to the FHIR <code>Condition</code> resource and shows up in the Care product UI as '''Symptoms'''.

'''Source:'''

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

A <code>Condition</code> lives across two layers, and the split matters when you read the code:

* The Django model (<code>care/emr/models/condition.py</code>) is storage. Its coded and timing fields (<code>code</code>, <code>body_site</code>, <code>onset</code>, <code>abatement</code>) are opaque <code>JSONField</code>s — the model says nothing about their shape.
* The Pydantic resource specs (<code>care/emr/resources/condition/spec.py</code>) are the API. They define the enums, the structure inside each JSON field, field validation, the value-set binding for <code>code</code>, and the separate read and write schemas.

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>Condition</code>
| A clinical condition, problem, diagnosis, or symptom recorded for a patient
|}

<code>Condition</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that provides <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>Condition</code> fields ==

=== Status & classification ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Condition|section=Status & classification|name=clinical_status|type=CharField(100), nullable|notes=Clinical state. Spec binds to [[#clinicalstatuschoices-values}}
{{Field|model=Condition|section=Status & classification|name=verification_status|type=CharField(100), nullable|notes=Level of certainty. Spec binds to [[#verificationstatuschoices-values}}
{{Field|model=Condition|section=Status & classification|name=category|type=CharField(100), nullable|notes=Classification. Spec binds to [[#categorychoices-values}}
{{Field|model=Condition|section=Status & classification|name=severity|type=CharField(100), nullable|notes=Subjective severity. Spec binds to [[#severitychoices-values}}
|}

=== Coded concepts ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Condition|section=Coded concepts|name=code|type=JSONField (default=dict, not null/blank)|notes=The condition itself. On write, a single [[#coding-shape}}
{{Field|model=Condition|section=Coded concepts|name=body_site|type=JSONField (default=dict, not null/blank)|notes=Anatomical location(s). Exists on the model but no current spec exposes it — never written or read through the standard <code>Condition</code> API.}}
|}

=== Timing ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Condition|section=Timing|name=onset|type=JSONField (default=dict)|notes=Choice-of-type onset, shaped by [[#conditiononsetspec-onset-shape}}
{{Field|model=Condition|section=Timing|name=abatement|type=JSONField (default=dict)|notes=When the condition resolved or went into remission. Shaped by [[#conditionabatementspec-abatement-shape}}
{{Field|model=Condition|section=Timing|name=recorded_date|type=DateTimeField, nullable|notes=When the condition was first recorded. Not exposed by the current specs.}}
|}

=== Context & notes ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Condition|section=Context & notes|name=patient|type=FK → Patient, on_delete=CASCADE|notes=Subject of the condition. Derived server-side from the encounter on create, never read from the client (<code>__exclude__</code>).}}
{{Field|model=Condition|section=Context & notes|name=encounter|type=FK → Encounter, nullable, on_delete=CASCADE|notes=Encounter the condition was recorded in. Set server-side on create (<code>__exclude__</code>); the client supplies a UUID in the spec, which is validated to exist.}}
{{Field|model=Condition|section=Context & notes|name=note|type=TextField, nullable|notes=Free-text clinical note.}}
|}

== Enums ==

Every enum is a <code>str, Enum</code> in <code>care/emr/resources/condition/spec.py</code>. The value stored and serialized is the string in the table.

=== <code>ClinicalStatusChoices</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>active</code>
|-
| <code>recurrence</code>
|-
| <code>relapse</code>
|-
| <code>inactive</code>
|-
| <code>remission</code>
|-
| <code>resolved</code>
|-
| <code>unknown</code>
|}

=== <code>VerificationStatusChoices</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>unconfirmed</code>
|-
| <code>provisional</code>
|-
| <code>differential</code>
|-
| <code>confirmed</code>
|-
| <code>refuted</code>
|-
| <code>entered_in_error</code>
|}

=== <code>CategoryChoices</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>problem_list_item</code>
|-
| <code>encounter_diagnosis</code>
|-
| <code>chronic_condition</code>
|}

=== <code>SeverityChoices</code> values ===

{| class="wikitable"
|-
! Value
|-
| <code>mild</code>
|-
| <code>moderate</code>
|-
| <code>severe</code>
|}

== Nested JSON shapes ==

These spec classes (all extend <code>EMRResource</code>) are the real structure behind the model's JSON fields.

=== <code>ConditionOnSetSpec</code> (<code>onset</code> shape) ===

{| class="wikitable"
|-
! Field
! Type
! Default
! Notes
{{Field|model=Condition|section=ConditionOnSetSpec (onset shape)|name=onset_datetime|type=datetime | None|notes=<code>None</code>}}
{{Field|model=Condition|section=ConditionOnSetSpec (onset shape)|name=onset_age|type=int | None|notes=<code>None</code>}}
{{Field|model=Condition|section=ConditionOnSetSpec (onset shape)|name=onset_string|type=str | None|notes=<code>None</code>}}
{{Field|model=Condition|section=ConditionOnSetSpec (onset shape)|name=note|type=str | None|notes=<code>None</code>}}
|}

=== <code>ConditionAbatementSpec</code> (<code>abatement</code> shape) ===

{| class="wikitable"
|-
! Field
! Type
! Default
! Notes
{{Field|model=Condition|section=ConditionAbatementSpec (abatement shape)|name=abatement_datetime|type=datetime | None|notes=<code>None</code>}}
{{Field|model=Condition|section=ConditionAbatementSpec (abatement shape)|name=abatement_age|type=int | None|notes=<code>None</code>}}
{{Field|model=Condition|section=ConditionAbatementSpec (abatement shape)|name=abatement_string|type=str | None|notes=<code>None</code>}}
{{Field|model=Condition|section=ConditionAbatementSpec (abatement shape)|name=note|type=str | None|notes=<code>None</code>}}
|}

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

<code>code</code> is a single [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/coding.py <code>Coding</code>], not a <code>CodeableConcept</code>. <code>extra="forbid"</code>.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Condition|section=Coding shape|name=system|type=str | None|notes=Code system URI (e.g. <code>http://snomed.info/sct</code>).}}
{{Field|model=Condition|section=Coding shape|name=version|type=str | None|notes=Code system version.}}
{{Field|model=Condition|section=Coding shape|name=code|type=str|notes='''Required.''' The code value.}}
{{Field|model=Condition|section=Coding shape|name=display|type=str | None|notes=Human-readable label.}}
|}

=== <code>code</code> value-set binding ===

On write, <code>code</code> is typed <code>ValueSetBoundCoding[CARE_CODITION_CODE_VALUESET.slug]</code> — a <code>Coding</code> checked against the Condition code value set (<code>care/emr/resources/condition/valueset.py</code>, slug <code>system-condition-code</code>), which covers SNOMED CT concepts that are <code>is-a</code> <code>404684003</code> (''Clinical finding''). Codes outside it are rejected on <code>ConditionSpec</code>, <code>ConditionUpdateSpec</code>, and <code>ChronicConditionUpdateSpec</code>. The read spec falls back to a plain <code>Coding</code> and skips value-set validation, so reads stay cheap.

== Resource specs (API schema) ==

Every spec extends <code>BaseConditionSpec</code> → <code>EMRResource</code> and round-trips through <code>serialize</code> (DB → Pydantic) and <code>de_serialize</code> (Pydantic → DB). <code>BaseConditionSpec</code> sets <code>__model__ = Condition</code>, sets <code>__exclude__ = ["patient", "encounter"]</code> (both server-maintained, never trusted from the client), and exposes <code>id: UUID4</code>.

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / behaviour
|-
| <code>BaseConditionSpec</code>
| shared base
| <code>id</code>; excludes <code>patient</code> and <code>encounter</code> from direct mapping.
|-
| <code>ConditionSpec</code>
| write · create
| <code>clinical_status?</code>, <code>verification_status</code> ('''required'''), <code>severity?</code>, <code>code</code> (value-set bound, '''required'''), <code>encounter</code> (UUID4, '''required'''), <code>onset</code> (<code>={}</code>), <code>abatement</code> (<code>={}</code>), <code>note?</code>, <code>category</code> ('''required'''). Validates that the encounter exists; on create sets <code>obj.encounter</code> and <code>obj.patient = encounter.patient</code>.
|-
| <code>ConditionUpdateSpec</code>
| write · update
| <code>clinical_status?</code>, <code>verification_status</code> ('''required'''), <code>severity?</code>, <code>code</code> (value-set bound, '''required'''), <code>onset</code> (<code>={}</code>), <code>abatement</code> (<code>={}</code>), <code>note?</code>. Does '''not''' accept <code>encounter</code>, <code>category</code>, or <code>patient</code>.
|-
| <code>ChronicConditionUpdateSpec</code>
| write · update (chronic)
| Extends <code>ConditionUpdateSpec</code> and adds <code>encounter</code> (UUID4). On deserialize, if <code>encounter</code> is set, resolves it (<code>get_object_or_404</code>) and assigns <code>obj.encounter</code>.
|-
| <code>ConditionReadSpec</code>
| read · detail/list
| <code>clinical_status</code>, <code>verification_status</code>, <code>category</code>, <code>criticality</code>, <code>severity</code> (all plain <code>str</code>), <code>code</code> (plain <code>Coding</code>), <code>encounter</code> (UUID4), <code>onset</code>, <code>abatement</code>, <code>created_by?</code>, <code>updated_by?</code>, <code>note?</code>, <code>created_date</code>, <code>modified_date</code>.
|}

=== Validation & server-side behaviour ===

* Encounter is required and verified on create. <code>ConditionSpec.validate_encounter_exists</code> rejects unknown encounter UUIDs; <code>perform_extra_deserialization</code> (create only) loads the encounter and derives <code>patient</code> from it. Clients never set <code>patient</code> or <code>encounter</code> directly.
* <code>verification_status</code> is mandatory on both <code>ConditionSpec</code> and <code>ConditionUpdateSpec</code>; <code>category</code> is mandatory only on create (<code>ConditionSpec</code>).
* <code>code</code> must belong to the bound value set (SNOMED CT clinical findings) on every write spec.
* <code>onset_datetime</code> cannot be in the future and is forced timezone-aware; <code>abatement_datetime</code> carries no such constraint.
* <code>ConditionReadSpec</code> exposes <code>criticality</code>, a string in the read schema with no backing column on the <code>Condition</code> model. The standard serializer never populates it, so it comes back unset.
* Read serialization (<code>perform_extra_serialization</code>) maps <code>id = external_id</code>, replaces <code>encounter</code> with its <code>external_id</code>, and expands <code>created_by</code>/<code>updated_by</code> via <code>serialize_audit_users</code> (cached <code>UserSpec</code>).
* <code>body_site</code> and <code>recorded_date</code> exist on the model but no current spec reads or writes them — storage-only, outside the standard <code>Condition</code> API surface.

== Related models ==

<code>Condition</code> links to two clinical records:

<syntaxhighlight lang="text">patient → FK Patient (CASCADE, server-derived from encounter)
encounter → FK Encounter (CASCADE, nullable; required on create)</syntaxhighlight>
Deleting a <code>Patient</code> or <code>Encounter</code> cascades to its <code>Condition</code> rows. The column allows a null <code>encounter</code>, but the standard create flow always supplies one and derives <code>patient</code> from it.

== Methods & save behaviour ==

* <code>serialize(obj)</code> and <code>de_serialize(obj)</code> (from <code>EMRResource</code>) convert between the <code>Condition</code> model and the spec. Field mapping uses the model's non-FK column names; <code>__exclude__</code> (<code>patient</code>, <code>encounter</code>) and <code>id</code>/<code>external_id</code> are skipped during deserialization.
* <code>ConditionSpec.perform_extra_deserialization(is_update=False, obj)</code> — create path: resolves the encounter and sets <code>obj.patient = obj.encounter.patient</code>.
* <code>ChronicConditionUpdateSpec.perform_extra_deserialization</code> — resolves and assigns <code>encounter</code> when provided.
* <code>ConditionReadSpec.perform_extra_serialization</code> — sets <code>id</code>/<code>encounter</code> external ids and serializes audit users.
* <code>external_id</code>, audit fields, <code>meta</code>/<code>history</code>, and soft-delete (<code>deleted</code>) are platform-maintained via [[References/Base models & conventions|<code>EMRBaseModel</code>]].

== API integration notes ==

* Send <code>code</code> as a structured <code>Coding</code> (<code>{system, code, display}</code>) drawn from the SNOMED CT clinical-finding value set, not as free text. Always include <code>verification_status</code>; add <code>category</code> and <code>encounter</code> when creating.
* <code>onset</code> and <code>abatement</code> are structured choice-of-type objects (<code>*_datetime</code>, <code>*_age</code>, <code>*_string</code>, <code>note</code>), not arbitrary JSON. <code>onset_datetime</code> must be timezone-aware and not in the future.
* Don't send <code>patient</code>, <code>external_id</code>, audit fields, or <code>deleted</code> from the client — the server owns them.

{{Related}}

References/Condition - Revision history

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

Admin: OHC identity seed