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

2026-07-06T04:02:31Z

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

← Older revision		Revision as of 09:32, 6 July 2026
Line 268:		Line 268:
	* The coded status fields (<code>clinical_status</code>, <code>verification_status</code>, <code>category</code>, <code>criticality</code>) accept only the enum values listed above; anything else is rejected on write.		* The coded status fields (<code>clinical_status</code>, <code>verification_status</code>, <code>category</code>, <code>criticality</code>) accept only the enum values listed above; anything else is rejected on write.
	* Never send <code>patient</code> or <code>copied_from</code> — both are server-maintained.		* Never send <code>patient</code> or <code>copied_from</code> — both are server-maintained.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:15Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Allergy Intolerance
|order=4
|introduced=3.0
|fhir=AllergyIntolerance
|model=AllergyIntolerance
|reference=References/Base models & conventions
}}

<code>AllergyIntolerance</code> records a patient's allergy or intolerance to a substance, scoped to the encounter where it was captured. Care aligns it to FHIR <code>AllergyIntolerance</code>. You touch this resource when recording a known allergy during an encounter or reading a patient's allergy list.

The Django model is the storage layer. Several of its fields are opaque <code>JSONField</code>s whose real structure lives only in the Pydantic resource specs, which also define the enums, validation, the bound value set, and the read/write API schemas.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/allergy_intolerance.py <code>care/emr/models/allergy_intolerance.py</code>]
* Specs: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/allergy_intolerance/spec.py <code>care/emr/resources/allergy_intolerance/spec.py</code>] · [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/allergy_intolerance/valueset.py <code>valueset.py</code>]
* Base resource: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>care/emr/resources/base.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>AllergyIntolerance</code>
| Records a patient's allergy or intolerance to a substance, scoped to an encounter
|}

<code>AllergyIntolerance</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>AllergyIntolerance</code> fields ==

=== Clinical classification ===

{| class="wikitable"
|-
! Field
! Type (storage)
! Spec type / values
! Notes
{{Field|model=AllergyIntolerance|section=Clinical classification|name=clinical_status|type=CharField(100), null|notes=<code>ClinicalStatusChoices</code>}}
{{Field|model=AllergyIntolerance|section=Clinical classification|name=verification_status|type=CharField(100), null|notes=<code>VerificationStatusChoices</code>}}
{{Field|model=AllergyIntolerance|section=Clinical classification|name=category|type=CharField(100), null|notes=<code>CategoryChoices</code>}}
{{Field|model=AllergyIntolerance|section=Clinical classification|name=criticality|type=CharField(100), null|notes=<code>CriticalityChoices</code>}}
{{Field|model=AllergyIntolerance|section=Clinical classification|name=allergy_intolerance_type|type=CharField(20), default "allergy"|notes=<code>AllergyIntoleranceTypeOptions</code>}}
|}

=== Substance & coding ===

{| class="wikitable"
|-
! Field
! Type (storage)
! Spec type / shape
! Notes
{{Field|model=AllergyIntolerance|section=Substance & coding|name=code|type=JSONField (default=dict, not null/blank)|notes=<code>Coding</code> bound to value set <code>system-allergy-code</code>}}
|}

<code>Coding</code> shape: <code>{ system?: str, version?: str, code: str (required), display?: str }</code> (<code>extra="forbid"</code>).

=== Timing ===

{| class="wikitable"
|-
! Field
! Type (storage)
! Spec type / shape
! Notes
{{Field|model=AllergyIntolerance|section=Timing|name=onset|type=JSONField (default=dict)|notes=<code>AllergyIntoleranceOnSetSpec</code>}}
{{Field|model=AllergyIntolerance|section=Timing|name=recorded_date|type=DateTimeField, null|notes=<code>datetime | None</code>}}
{{Field|model=AllergyIntolerance|section=Timing|name=last_occurrence|type=DateTimeField, null|notes=<code>datetime | None</code>}}
|}

<code>AllergyIntoleranceOnSetSpec</code> shape:

{| class="wikitable"
|-
! Sub-field
! Type
! Required
! Default
|-
| <code>onset_datetime</code>
| <code>datetime</code>
| No
| <code>None</code>
|-
| <code>onset_age</code>
| <code>int</code>
| No
| <code>None</code>
|-
| <code>onset_string</code>
| <code>str</code>
| No
| <code>None</code>
|-
| <code>note</code>
| <code>str</code>
| '''Yes'''
| —
|}

=== Context & notes ===

{| class="wikitable"
|-
! Field
! Type (storage)
! Spec type
! Notes
{{Field|model=AllergyIntolerance|section=Context & notes|name=patient|type=FK → Patient (CASCADE)|notes=excluded from specs}}
{{Field|model=AllergyIntolerance|section=Context & notes|name=encounter|type=FK → Encounter (CASCADE)|notes=<code>UUID4</code>}}
{{Field|model=AllergyIntolerance|section=Context & notes|name=note|type=TextField, null|notes=<code>str | None</code>}}
{{Field|model=AllergyIntolerance|section=Context & notes|name=copied_from|type=BigIntegerField, null (default=None)|notes=not exposed}}
|}

== Enum values ==

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

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

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

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

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

{| class="wikitable"
|-
! Value
|-
| <code>food</code>
|-
| <code>medication</code>
|-
| <code>environment</code>
|-
| <code>biologic</code>
|}

=== <code>CriticalityChoices</code> ===

{| class="wikitable"
|-
! Value
|-
| <code>low</code>
|-
| <code>high</code>
|-
| <code>unable_to_assess</code>
|}

=== <code>AllergyIntoleranceTypeOptions</code> ===

{| class="wikitable"
|-
! Value
|-
| <code>allergy</code> (default)
|-
| <code>intolerance</code>
|}

== Bound value set ==

{| class="wikitable"
|-
! Value set
! Slug
! System
! Status
|-
| <code>CARE_ALLERGY_CODE_VALUESET</code> ("Allergy")
| <code>system-allergy-code</code>
| SNOMED CT (<code>http://snomed.info/sct</code>)
| <code>active</code>
|}

On write, <code>code</code> binds to this value set via <code>ValueSetBoundCoding[...slug]</code>, which validates the submitted <code>Coding</code> against the value set (<code>validate_valueset</code>). The compose admits SNOMED CT concepts that are <code>is-a</code> descendants of: <code>105590001</code>, <code>418038007</code>, <code>267425008</code>, <code>29736007</code>, <code>340519003</code>, <code>190753003</code>, <code>413427002</code>, <code>716186003</code>. The value set is also registered as a system (<code>register_as_system()</code>).

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which provides <code>serialize</code> (DB object → pydantic, via <code>model_construct</code>) and <code>de_serialize</code> (pydantic → DB object), plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>BaseAllergyIntoleranceSpec</code> sets <code>__model__ = AllergyIntolerance</code> and <code>__exclude__ = ["patient", "encounter"]</code>; those two fields skip auto-mapping and are wired by the hooks instead. The base also carries <code>meta</code> on every spec.

{| class="wikitable"
|-
! Spec class
! Role
! Fields exposed
|-
| <code>BaseAllergyIntoleranceSpec</code>
| shared base
| <code>id: UUID4</code>
|-
| <code>AllergyIntoleranceWriteSpec</code>
| write · create
| <code>clinical_status</code>, <code>verification_status</code>, <code>category</code>, <code>criticality</code>, <code>last_occurrence?</code>, <code>recorded_date?</code>, <code>encounter</code> (UUID4), <code>code</code> (bound Coding), <code>onset</code> (default <code>{}</code>), <code>allergy_intolerance_type</code> (default <code>allergy</code>), <code>note?</code>
|-
| <code>AllergyIntoleranceUpdateSpec</code>
| write · update
| <code>clinical_status</code>, <code>verification_status</code>, <code>criticality</code>, <code>last_occurrence?</code>, <code>note?</code>, <code>encounter</code> (UUID4), <code>allergy_intolerance_type</code> (default <code>allergy</code>)
|-
| <code>AllergyIntoleranceReadSpec</code>
| read · list & detail
| <code>id</code>, <code>clinical_status</code>, <code>verification_status</code>, <code>category</code>, <code>criticality</code>, <code>code</code> (Coding), <code>encounter</code> (UUID4), <code>onset</code>, <code>last_occurrence?</code>, <code>recorded_date?</code>, <code>note?</code>, <code>allergy_intolerance_type</code>, <code>created_by?</code>, <code>updated_by?</code>, <code>created_date</code>, <code>modified_date</code>
|-
| <code>AllergyIntoleranceOnSetSpec</code>
| nested (shape of <code>onset</code> JSON)
| <code>onset_datetime?</code>, <code>onset_age?</code>, <code>onset_string?</code>, <code>note</code> (required)
|}

* <code>category</code>, <code>code</code>, <code>onset</code>, and <code>recorded_date</code> are accepted only on create (<code>AllergyIntoleranceWriteSpec</code>) and absent from <code>AllergyIntoleranceUpdateSpec</code> — once set, the update path cannot change them.
* <code>AllergyIntoleranceReadSpec</code> types the coded fields as plain <code>str</code> and <code>code</code> as <code>Coding</code>, and skips value-set re-validation, relying on <code>model_construct</code> for speed.

=== Validation ===

* <code>encounter</code> (both write specs): <code>validate_encounter_exists</code> rejects with <code>"Encounter not found"</code> when no <code>Encounter</code> has that <code>external_id</code>.
* <code>code</code> (create): validated against value set <code>system-allergy-code</code> — must be a permitted SNOMED CT allergy concept.
* <code>onset.note</code> is required whenever an <code>onset</code> object is supplied.
* <code>datetime</code> fields are stored as-is. The base enforces tz-aware handling for period-style values through <code>PeriodSpec</code> (start ≤ end, both tz-aware), but <code>AllergyIntolerance</code> uses scalar datetimes rather than a <code>PeriodSpec</code>.

=== Server-side side effects ===

* '''Create''' (<code>AllergyIntoleranceWriteSpec.perform_extra_deserialization</code>): resolves <code>encounter</code> by <code>external_id</code>, sets <code>obj.encounter</code>, then sets <code>obj.patient = obj.encounter.patient</code>. The client never sends <code>patient</code> directly.
* '''Update''' (<code>AllergyIntoleranceUpdateSpec.perform_extra_deserialization</code>): when <code>encounter</code> is present, re-resolves it and sets <code>obj.encounter</code>.
* '''Read''' (<code>AllergyIntoleranceReadSpec.perform_extra_serialization</code>): sets <code>mapping["id"] = obj.external_id</code>, sets <code>encounter</code> to <code>obj.encounter.external_id</code>, and serializes audit users (<code>created_by</code> / <code>updated_by</code>) via <code>serialize_audit_users</code>.

== Methods & save behaviour ==

* <code>serialize</code> / <code>de_serialize</code> are inherited from <code>EMRResource</code>. <code>de_serialize</code> maps only DB fields that are neither in <code>__exclude__</code> nor <code>id</code>/<code>external_id</code>, then calls <code>perform_extra_deserialization</code> for the encounter/patient wiring above.
* <code>patient</code> is always derived from the encounter on create; no client payload can set it.
* <code>copied_from</code> is platform-maintained for propagated/copied records and belongs to no spec.
* <code>patient</code> and <code>encounter</code> both <code>CASCADE</code>-delete, so an allergy record never outlives its patient or encounter.

== API integration notes ==

* API field names follow the spec classes above. <code>encounter</code> is sent and returned as a UUID <code>external_id</code>, not a numeric FK.
* Submit <code>code</code> as a <code>Coding</code> drawn from the bound value set <code>system-allergy-code</code>, not free text, so allergies can be matched against medications and other business logic.
* The coded status fields (<code>clinical_status</code>, <code>verification_status</code>, <code>category</code>, <code>criticality</code>) accept only the enum values listed above; anything else is rejected on write.
* Never send <code>patient</code> or <code>copied_from</code> — both are server-maintained.

{{Related}}

References/Allergy Intolerance - Revision history

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

Admin: OHC identity seed