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

2026-07-06T04:16:20Z

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

← Older revision		Revision as of 09:46, 6 July 2026
Line 214:		Line 214:
	* <code>information_source</code> is what separates a self-reported or third-party statement from an actively managed prescription ([[References/Medication Request\|<code>MedicationRequest</code>]]).		* <code>information_source</code> is what separates a self-reported or third-party statement from an actively managed prescription ([[References/Medication Request\|<code>MedicationRequest</code>]]).
	* <code>external_id</code> (UUID), <code>created_by</code>/<code>updated_by</code>, <code>created_date</code>/<code>modified_date</code>, <code>history</code>, and <code>meta</code> are platform-maintained — don't set them from clients.		* <code>external_id</code> (UUID), <code>created_by</code>/<code>updated_by</code>, <code>created_date</code>/<code>modified_date</code>, <code>history</code>, and <code>meta</code> are platform-maintained — don't set them from clients.

			{{Navbox medications}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:26Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=medications
|title=Medication Statement
|order=4
|introduced=3.0
|model=MedicationStatement
|reference=References/Base models & conventions
}}

A <code>MedicationStatement</code> records a medication the patient is taking, has taken, or intends to take, as reported by the patient, a relative, or a clinician rather than actively prescribed or dispensed. Reach for it when you're capturing a medication history rather than driving an order. It aligns with the FHIR <code>MedicationStatement</code> resource.

The Django model stores <code>medication</code> and <code>effective_period</code> as opaque <code>JSONField</code>s. Their real structure comes from the Pydantic resource specs in <code>care/emr/resources/medication/statement/</code>, which define the enums, nested JSON shapes, validation, the value-set binding on <code>medication</code>, and the read/write API schemas. This page covers both layers.

'''Source:'''

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

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>MedicationStatement</code>
| A record of a medication the patient is taking, has taken, or intends to take — as reported rather than actively prescribed
|}

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

== <code>MedicationStatement</code> fields ==

'''Type''' is the Django storage type. '''Spec shape''' is the structured shape the Pydantic resource spec enforces when reading and writing over the API.

=== Statement details ===

{| class="wikitable"
|-
! Field
! Type
! Spec shape
! Notes
{{Field|model=MedicationStatement|section=Statement details|name=status|type=CharField(100)|notes=<code>MedicationStatementStatus</code> enum}}
{{Field|model=MedicationStatement|section=Statement details|name=reason|type=CharField(100)|notes=<code>str | None</code>}}
{{Field|model=MedicationStatement|section=Statement details|name=medication|type=JSONField (default=dict)|notes=<code>Coding</code> bound to the <code>system-medication</code> value set}}
{{Field|model=MedicationStatement|section=Statement details|name=information_source|type=CharField(100)|notes=<code>MedicationStatementInformationSourceType</code> enum | <code>None</code>}}
{{Field|model=MedicationStatement|section=Statement details|name=effective_period|type=JSONField (default=dict)|notes=<code>PeriodSpec</code> | <code>None</code>}}
{{Field|model=MedicationStatement|section=Statement details|name=dosage_text|type=TextField|notes=<code>str | None</code>}}
{{Field|model=MedicationStatement|section=Statement details|name=note|type=TextField|notes=<code>str | None</code>}}
|}

=== Relationships ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=MedicationStatement|section=Relationships|name=patient|type=FK → Patient|notes=<code>on_delete=CASCADE</code>. The patient the statement is about. Derived server-side from the encounter — never accepted from clients.}}
{{Field|model=MedicationStatement|section=Relationships|name=encounter|type=FK → Encounter|notes=<code>on_delete=CASCADE</code>. The encounter the statement was recorded in. Supplied as a UUID on create.}}
|}

<syntaxhighlight lang="text">patient → FK Patient (CASCADE)
encounter → FK Encounter (CASCADE)</syntaxhighlight>
Deleting a patient or encounter deletes its medication statements.

== Enum values ==

=== <code>MedicationStatementStatus</code> values ===

<code>MedicationStatementStatus(str, Enum)</code> in <code>spec.py</code>, bound to <code>status</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| The medication is being taken
|-
| <code>on_hold</code>
| Taking has been paused
|-
| <code>completed</code>
| The course has finished
|-
| <code>stopped</code>
| The medication was stopped
|-
| <code>unknown</code>
| Status is not known
|-
| <code>entered_in_error</code>
| The record was entered in error
|-
| <code>not_taken</code>
| The patient is not taking the medication
|-
| <code>intended</code>
| The patient intends to take the medication
|}

=== <code>MedicationStatementInformationSourceType</code> values ===

<code>MedicationStatementInformationSourceType(str, Enum)</code> in <code>spec.py</code>, bound to <code>information_source</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>related_person</code>
| A relative or related person reported it
|-
| <code>practitioner</code>
| A clinician reported it
|-
| <code>patient</code>
| The patient self-reported it
|}

== Nested JSON shapes ==

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

<code>medication</code> is stored as JSON but typed as a single <code>Coding</code> (from <code>care/emr/resources/common/coding.py</code>), not a <code>CodeableConcept</code>. The spec sets <code>extra="forbid"</code>, so unrecognized keys are rejected.

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

==== Bound value set ====

<code>medication</code> is declared as <code>ValueSetBoundCoding[CARE_MEDICATION_VALUESET.slug]</code>. On write, <code>code</code> is validated against the '''<code>system-medication</code>''' value set ([<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/medication/valueset/medication.py <code>medication.py</code>]), which includes SNOMED CT concepts under the constraint <code><< 763158003 |Medicinal product|</code>. Any code outside the set is rejected.

<blockquote>The <code>care/emr/resources/medication/valueset/</code> directory holds further value sets for other medication resources (route, body site, administration method, additional instruction, as-needed reason, medication-not-given reason). <code>MedicationStatement</code> binds only <code>medication</code> → <code>system-medication</code>.
</blockquote>
=== <code>PeriodSpec</code> shape ===

<code>effective_period</code> is stored as JSON but typed as <code>PeriodSpec</code> (from <code>care/emr/resources/base.py</code>).

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=MedicationStatement|section=PeriodSpec shape|name=start|type=datetime | None|notes=Must be timezone-aware if present; naive datetimes are rejected}}
{{Field|model=MedicationStatement|section=PeriodSpec shape|name=end|type=datetime | None|notes=Must be timezone-aware if present}}
|}

<code>validate_period</code> (mode <code>after</code>) rejects a naive <code>start</code>/<code>end</code> and requires <code>start</code> to be no greater than <code>end</code>.

== Resource specs (API schema) ==

Every spec subclasses <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which provides <code>serialize</code> (DB object → pydantic) and <code>de_serialize</code> (pydantic → DB object). <code>__model__ = MedicationStatement</code>, and <code>__exclude__ = ["patient", "encounter"]</code> holds those two fields out of the generic field copy so the extra hooks set them instead.

{| class="wikitable"
|-
! Spec class
! Role
! Fields exposed
|-
| <code>BaseMedicationStatementSpec</code>
| shared base
| <code>id</code>, <code>status</code>, <code>reason</code>, <code>medication</code>, <code>dosage_text</code>, <code>effective_period</code>, <code>encounter</code>, <code>information_source</code>, <code>note</code>
|-
| <code>MedicationStatementSpec</code>
| write · create
| Inherits <code>BaseMedicationStatementSpec</code>; adds <code>encounter</code> existence validation + extra deserialization
|-
| <code>MedicationStatementUpdateSpec</code>
| write · update
| <code>status</code>, <code>effective_period</code>, <code>note</code> only
|-
| <code>MedicationStatementReadSpec</code>
| read · list & detail
| Inherits base; adds <code>created_by</code>, <code>updated_by</code> (<code>UserSpec</code>), <code>created_date</code>, <code>modified_date</code>
|}

What the specs validate and maintain on your behalf:

* '''<code>encounter</code> must exist''' — <code>MedicationStatementSpec.validate_encounter_exists</code>, a <code>field_validator</code> on <code>encounter</code>, raises <code>"Encounter not found"</code> unless an <code>Encounter</code> with that <code>external_id</code> exists.
* '''<code>patient</code> is derived server-side''' — <code>MedicationStatementSpec.perform_extra_deserialization</code> runs only on create (<code>is_update</code> false): it resolves the <code>Encounter</code> from the supplied UUID and sets <code>obj.patient = obj.encounter.patient</code>. Clients never send <code>patient</code>.
* '''Updates are narrow''' — <code>MedicationStatementUpdateSpec</code> accepts only <code>status</code>, <code>effective_period</code>, and <code>note</code>. <code>medication</code>, <code>reason</code>, <code>dosage_text</code>, <code>information_source</code>, and <code>encounter</code> can't be changed through it.
* '''Read serialization''' — <code>MedicationStatementReadSpec.perform_extra_serialization</code> sets <code>id = obj.external_id</code>, <code>encounter = obj.encounter.external_id</code>, and serializes audit users via <code>serialize_audit_users</code> (<code>created_by</code>/<code>updated_by</code> as <code>UserSpec</code>).
* '''<code>medication</code> value-set check''' — runs at validation time against <code>Coding.code</code> (see [[#bound-value-set|Bound value set]]).
* '''<code>effective_period</code> tz-awareness and ordering''' — enforced by <code>PeriodSpec</code> (see [[#periodspec-shape|<code>PeriodSpec</code> shape]]).

There is no <code>status_history</code>. <code>status</code> is a single current value, not an appended log.

== Methods & save behaviour ==

* From [[References/Base models & conventions|<code>EMRBaseModel</code>]]: <code>external_id</code> (UUID), audit fields, soft delete. Deletes are soft — a removed statement stays in the table with <code>deleted=True</code> and is hidden by the default manager.
* Create flow: client sends <code>MedicationStatementSpec</code> → <code>de_serialize</code> copies scalar/JSON fields → <code>perform_extra_deserialization</code> resolves <code>encounter</code> and back-fills <code>patient</code> → model saved.
* Read flow: <code>MedicationStatementReadSpec.serialize(obj)</code> copies fields, then <code>perform_extra_serialization</code> injects <code>id</code>, <code>encounter</code> (as UUIDs), and audit users.

== API integration notes ==

* Exposed through Care's REST API, aligned with FHIR <code>MedicationStatement</code>. Use the spec field names above for payloads.
* <code>medication</code> is a single SNOMED CT <code>Coding</code> object whose <code>code</code> must be in the <code>system-medication</code> value set — not a free CodeableConcept, and not a scalar string.
* <code>effective_period</code> datetimes must be timezone-aware and ordered (<code>start ≤ end</code>).
* <code>encounter</code> goes in as a UUID; <code>patient</code> is derived from it server-side and must not be sent.
* Updates flow through <code>MedicationStatementUpdateSpec</code> and can touch only <code>status</code>, <code>effective_period</code>, and <code>note</code>.
* <code>information_source</code> is what separates a self-reported or third-party statement from an actively managed prescription ([[References/Medication Request|<code>MedicationRequest</code>]]).
* <code>external_id</code> (UUID), <code>created_by</code>/<code>updated_by</code>, <code>created_date</code>/<code>modified_date</code>, <code>history</code>, and <code>meta</code> are platform-maintained — don't set them from clients.

{{Related}}

References/Medication Statement - Revision history

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

Admin: OHC identity seed