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

2026-07-06T04:03:58Z

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

← Older revision		Revision as of 09:33, 6 July 2026
Line 279:		Line 279:
	* <code>verification_details</code> is read-only on write and comes back with <code>verified_by</code> expanded to full user objects.		* <code>verification_details</code> is read-only on write and comes back with <code>verified_by</code> expanded to full user objects.
	* The Pydantic enums, not the database columns, enforce the allowed <code>status</code>, <code>category</code>, and <code>decision</code> values.		* The Pydantic enums, not the database columns, enforce the allowed <code>status</code>, <code>category</code>, and <code>decision</code> values.

			{{Navbox clinical}}

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

Admin: OHC identity seed

2026-07-04T22:44:19Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=clinical
|title=Consent
|order=8
|introduced=3.0
|fhir=Consent
|model=Consent
|reference=References/User & Skills
}}

A <code>Consent</code> records a patient's permit-or-deny decision for a category of activity, scoped to an encounter. You write one when capturing a patient's agreement (or refusal) to treatment, research, privacy disclosure, or an advance directive.

The Django model only stores data: <code>status</code>, <code>category</code>, and <code>decision</code> are bare <code>CharField</code>s, and <code>period</code> / <code>verification_details</code> are opaque <code>JSONField</code>s. Allowed enum values, the nested JSON shapes, validation, and the read/write schema split all live in the Pydantic resource specs at <code>care/emr/resources/consent/spec.py</code>, built on <code>EMRResource</code>.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/consent.py <code>care/emr/models/consent.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/consent/spec.py <code>care/emr/resources/consent/spec.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>Consent</code>
| Records a patient's consent decision (permit/deny) for a category of activity, scoped to an encounter
|}

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

Storage type is the Django column; Spec type is the shape the API enforces.

{| class="wikitable"
|-
! Field
! Storage type
! Spec type
! Notes
|-
| <code>status</code>
| <code>CharField(50)</code>
| <code>ConsentStatusChoices</code> (enum)
| Required. Lifecycle state. See [[#consentstatuschoices-values
|-
| <code>category</code>
| <code>CharField(50)</code>
| <code>CategoryChoice</code> (enum)
| Required. What the consent is for. See [[#categorychoice-values
|-
| <code>date</code>
| <code>DateTimeField</code>
| <code>datetime</code>
| Required. When the consent was recorded
|-
| <code>period</code>
| <code>JSONField</code> (default <code>dict</code>)
| <code>PeriodSpec { start, end }</code>
| Validity window. Both ends must be tz-aware; <code>start ≤ end</code>; and on create, <code>start ≥ date</code>. See [[#periodspec-nested-shape
|-
| <code>encounter</code>
| <code>FK → Encounter</code> (<code>CASCADE</code>, <code>related_name="consents"</code>)
| <code>UUID4</code> (<code>external_id</code>)
| Required. The encounter this consent applies to; deleting the encounter deletes its consents. Listed in <code>__exclude__</code>, so it skips the generic DB mapping and is resolved by hand — see [[#methods--save-behaviour
|-
| <code>decision</code>
| <code>CharField(10)</code>
| <code>DecisionType</code> (enum)
| Required. <code>permit</code> / <code>deny</code>. See [[#decisiontype-values
|-
| <code>verification_details</code>
| <code>JSONField</code> (default <code>list</code>)
| <code>list[ConsentVerificationSpec]</code>
| Read-only on the API; one entry per verification record. See [[#consentverificationspec-nested-shape
|-
| <code>note</code>
| <code>TextField</code> (null, blank)
| <code>str | None</code>
| Optional free-text note
|}

<blockquote>Note: <code>source_attachments</code> is '''not''' a model field. It is derived at serialize time from <code>FileUpload</code> rows (see [[#resource-specs-api-schema|Resource specs]]).
</blockquote>
== Enums ==

=== <code>ConsentStatusChoices</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Consent is being drafted, not yet in force
|-
| <code>active</code>
| Consent is in force
|-
| <code>inactive</code>
| Consent is no longer in force
|-
| <code>not_done</code>
| Consent activity did not occur
|-
| <code>entered_in_error</code>
| Consent was recorded in error
|}

=== <code>CategoryChoice</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>research</code>
| Consent for research participation
|-
| <code>patient_privacy</code>
| Patient privacy / information disclosure consent
|-
| <code>treatment</code>
| Consent to treatment
|-
| <code>dnr</code>
| Do-not-resuscitate directive
|-
| <code>comfort_care</code>
| Comfort / palliative care directive
|-
| <code>acd</code>
| Advance care directive
|-
| <code>adr</code>
| Advance directive (other)
|}

<blockquote>A <code>consent_document</code> category (LOINC 59284-0) exists in migrations only and is '''not''' an accepted API value.
</blockquote>
=== <code>DecisionType</code> values ===

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>permit</code>
| Consent is granted
|-
| <code>deny</code>
| Consent is refused
|}

=== <code>VerificationType</code> values ===

Used inside <code>ConsentVerificationSpec.verification_type</code>.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>family</code>
| Verified by a family member
|-
| <code>validation</code>
| Verified through validation
|}

== Nested JSON shapes ==

=== <code>PeriodSpec</code> nested shape ===

The <code>period</code> field deserializes to <code>PeriodSpec</code> (from <code>care/emr/resources/base.py</code>). The model default is <code>dict</code>, so an absent period stores <code>{}</code>.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Consent|section=PeriodSpec nested shape|name=start|type=datetime | None|notes=Default <code>None</code>. Must be '''timezone-aware''' if set}}
{{Field|model=Consent|section=PeriodSpec nested shape|name=end|type=datetime | None|notes=Default <code>None</code>. Must be '''timezone-aware''' if set}}
|}

<code>PeriodSpec.validate_period</code> (mode <code>after</code>) enforces:

* <code>start</code> must be tz-aware (else <code>"Start Date must be timezone aware"</code>).
* <code>end</code> must be tz-aware (else <code>"End Date must be timezone aware"</code>).
* If both are set, <code>start ≤ end</code> (else <code>"Start Date cannot be greater than End Date"</code>).

=== <code>ConsentVerificationSpec</code> nested shape ===

This is the shape each <code>verification_details</code> entry takes on write. On read, <code>verified_by</code> is expanded — see below.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Consent|section=ConsentVerificationSpec nested shape|name=verified|type=bool|notes=Required. Whether the consent was verified}}
{{Field|model=Consent|section=ConsentVerificationSpec nested shape|name=verified_by|type=UUID4 | None|notes=Default <code>None</code>. On write, the verifying user's <code>external_id</code>. On read, replaced by a full <code>UserSpec</code> object}}
{{Field|model=Consent|section=ConsentVerificationSpec nested shape|name=verification_date|type=datetime | None|notes=Default <code>None</code>}}
{{Field|model=Consent|section=ConsentVerificationSpec nested shape|name=verification_type|type=VerificationType|notes=Required. <code>family</code> / <code>validation</code>}}
{{Field|model=Consent|section=ConsentVerificationSpec nested shape|name=note|type=str | None|notes=Default <code>None</code>}}
|}

== Resource specs (API schema) ==

Every spec subclasses <code>EMRResource</code> through <code>ConsentBaseSpec</code>. <code>serialize</code> builds the read schema from the model; <code>de_serialize</code> writes a model from the payload, skipping <code>id</code>/<code>external_id</code> and any <code>__exclude__</code> field. <code>ConsentBaseSpec</code> sets <code>__exclude__ = ["encounter"]</code>, so the encounter FK never round-trips through the generic mapping — the deserialization hooks resolve it instead.

{| class="wikitable"
|-
! Spec class
! Role
! Exposes / behaviour
|-
| <code>ConsentBaseSpec</code>
| shared base
| <code>id</code>, <code>status</code>, <code>category</code>, <code>date</code>, <code>period</code>, <code>encounter</code> (UUID4), <code>decision</code>, <code>note</code>. <code>__model__ = Consent</code>, <code>__exclude__ = ["encounter"]</code>
|-
| <code>ConsentCreateSpec</code>
| write · create
| Same fields as base (all required except <code>id</code>, <code>note</code>). Validates <code>period.start ≥ date</code>; resolves <code>encounter</code> from <code>external_id</code> → <code>Encounter</code> instance
|-
| <code>ConsentUpdateSpec</code>
| write · update
| All fields optional (<code>status</code>, <code>category</code>, <code>date</code>, <code>period</code>, <code>encounter</code>, <code>decision</code>, <code>note</code> → <code>None</code>). Keeps the existing <code>encounter</code> and ignores any supplied value
|-
| <code>ConsentListSpec</code>
| read · list
| Base fields plus derived <code>source_attachments: list</code> and expanded <code>verification_details: list</code>
|-
| <code>ConsentRetrieveSpec</code>
| read · detail
| Identical to <code>ConsentListSpec</code> (<code>pass</code>)
|}

The schema nests [[#periodspec-nested-shape|<code>PeriodSpec</code>]] for the <code>period</code> field and [[#consentverificationspec-nested-shape|<code>ConsentVerificationSpec</code>]] for entries of <code>verification_details</code>.

=== Validation ===

* '''Create only''' (<code>ConsentCreateSpec.validate_period_and_date</code>, mode <code>after</code>): if <code>period.start</code> is set and <code>period.start < date</code>, raises <code>"Start of the period cannot be before than the Consent date"</code>.
* '''All specs''' (via <code>PeriodSpec</code>): tz-aware <code>start</code>/<code>end</code>, and <code>start ≤ end</code>.
* Enum fields (<code>status</code>, <code>category</code>, <code>decision</code>) reject any value outside their enum. On <code>ConsentUpdateSpec</code> they may be omitted (<code>None</code>).

=== Server-maintained behaviour ===

* '''Encounter resolution (create):''' <code>ConsentCreateSpec.perform_extra_deserialization</code> sets <code>obj.encounter = Encounter.objects.get(external_id=self.encounter)</code> when not an update.
* '''Encounter immutability (update):''' <code>ConsentUpdateSpec.perform_extra_deserialization</code> copies <code>self.encounter = obj.encounter</code>, so an update can't reassign the encounter through the API.
* '''Source attachments (read):''' <code>ConsentListSpec.perform_extra_serialization</code> sets <code>source_attachments</code> to the serialized <code>FileUploadListSpec</code> for every <code>FileUpload</code> where <code>associating_id == consent.external_id</code>, <code>file_category == consent_attachment</code>, and <code>file_type == consent</code>.
* '''Verifier expansion (read):''' each <code>verification_details[i].verified_by</code> is replaced with a full <code>UserSpec</code> (<code>User.objects.get(external_id=...)</code>).
* '''Identifiers (read):''' <code>id</code> is set to <code>external_id</code>; <code>encounter</code> is serialized as <code>obj.encounter.external_id</code>.

== Related models ==

<code>Consent</code> points at one <code>Encounter</code>, and an encounter carries many consents through the <code>consents</code> reverse relation:

<syntaxhighlight lang="text">encounter → FK Encounter (CASCADE, related_name="consents")</syntaxhighlight>
The owning patient is reached through <code>encounter</code>. Coded values (<code>status</code>, <code>category</code>, <code>decision</code>) and structured JSON (<code>period</code>, <code>verification_details</code>) are validated by the Pydantic specs at the API layer, not by database constraints.

Read schemas also reach into <code>FileUpload</code> (consent attachments) and <code>User</code> (verifiers) at serialize time.

== Methods & save behaviour ==

* <code>EMRResource.serialize(obj)</code> builds the read object: it copies the non-FK model fields present on the spec, runs <code>perform_extra_serialization</code> (id, encounter <code>external_id</code>, <code>source_attachments</code>, expanded <code>verification_details</code>), and stamps <code>version</code>.
* <code>EMRResource.de_serialize(obj=None)</code> builds or updates the model: it dumps the spec (<code>exclude_defaults=True</code>), assigns matching DB fields (skipping <code>id</code>/<code>external_id</code> and <code>__exclude__</code>), then runs <code>perform_extra_deserialization</code>.
* Because <code>encounter</code> is in <code>__exclude__</code>, the generic loop never touches it — create resolves it from <code>external_id</code>, update preserves the existing FK.
* <code>status</code> is a plain field. Setting it to <code>entered_in_error</code> (or anything else) is a direct write with no status-history side effect.

== API integration notes ==

* Payload field names match the spec, and <code>encounter</code> is the UUID <code>external_id</code>, not the numeric PK — a common source of 404s on create.
* The model maps to the FHIR <code>Consent</code> resource; <code>status</code>, <code>category</code>, <code>decision</code>, and <code>period</code> line up with their FHIR counterparts.
* <code>verification_details</code> is read-only on write and comes back with <code>verified_by</code> expanded to full user objects.
* The Pydantic enums, not the database columns, enforce the allowed <code>status</code>, <code>category</code>, and <code>decision</code> values.

{{Related}}

References/Consent - Revision history

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

Admin: OHC identity seed