Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

2026-07-06T04:25:11Z

Add Navbox platform (via update-page on MediaWiki MCP Server)

← Older revision		Revision as of 09:55, 6 July 2026
Line 258:		Line 258:

	<code>metadata</code> carries display hints (<code>color</code>, <code>icon</code>) without a schema migration, shaped by <code>TagConfigMetadata</code>.		<code>metadata</code> carries display hints (<code>color</code>, <code>icon</code>) without a schema migration, shaped by <code>TagConfigMetadata</code>.

			{{Navbox platform}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:45:38Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=platform
|title=Tagging
|order=6
|introduced=3.0
|model=Tagging
|reference=References/Base models & conventions
}}

A <code>TagConfig</code> defines one tag: its label, category, scope, and place in a tag tree. Tags are hierarchical labels you attach to resources — patients, encounters, charge items — to classify and filter them. You manage the definitions through <code>TagConfig</code>; the applied tags live as integer ID arrays on the tagged resources.

Two layers back the tag. The Django model (<code>care/emr/models/tag_config.py</code>) is storage — it holds opaque <code>JSONField</code>s (<code>metadata</code>, <code>cached_parent_json</code>) whose structure it never describes. The Pydantic resource specs (<code>care/emr/resources/tag/config_spec.py</code>) are the API and implementation layer: they pin down the enums, give those JSON fields a real shape, run field validation, and split read from write.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/tag_config.py <code>care/emr/models/tag_config.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/tag/config_spec.py <code>care/emr/resources/tag/config_spec.py</code>]
* Cache invalidation: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/tag/cache_invalidation.py <code>care/emr/resources/tag/cache_invalidation.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>TagConfig</code>
| Definition of a single tag — its display, category, scope, status, metadata, and position in the tag tree
|}

<code>TagConfig</code> extends [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base providing <code>external_id</code>, the audit fields <code>created_by</code>/<code>updated_by</code> and <code>created_date</code>/<code>modified_date</code>, soft-delete via <code>deleted</code>, and <code>history</code>/<code>meta</code> JSON. Applied tag IDs live on the tagged resource itself — for example <code>Patient.instance_tags</code> / <code>Patient.facility_tags</code> and <code>Encounter.tags</code>.

== <code>TagConfig</code> fields ==

=== Scope ===

A tag is scoped to at most one owner — an instance-wide organization, a facility-scoped organization, or a facility.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Tagging|section=Scope|name=facility|type=FK → Facility|notes=<code>PROTECT</code>, nullable, <code>default=None</code>. Facility that owns the tag}}
{{Field|model=Tagging|section=Scope|name=facility_organization|type=FK → FacilityOrganization|notes=<code>CASCADE</code>, nullable. Owning facility organization. Not allowed on instance-level (no-facility) tags}}
{{Field|model=Tagging|section=Scope|name=organization|type=FK → Organization|notes=<code>CASCADE</code>, nullable. Owning instance-wide organization}}
{{Field|model=Tagging|section=Scope|name=resource|type=CharField(255)|notes=The resource type the tag applies to. Constrained by <code>TagResource</code> in the write spec (see [[#tagresource-values}}
|}

=== Display & classification ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Tagging|section=Display & classification|name=status|type=CharField(255)|notes=Lifecycle status. Constrained by <code>TagStatus</code> in the spec — <code>active</code> / <code>archived</code> (see [[#tagstatus-values}}
{{Field|model=Tagging|section=Display & classification|name=display|type=CharField(255)|notes=Human-readable label. Required in the spec}}
{{Field|model=Tagging|section=Display & classification|name=description|type=TextField|notes=Nullable, blank-able. Required key in the base spec but accepts <code>null</code>}}
{{Field|model=Tagging|section=Display & classification|name=category|type=CharField(255)|notes=Grouping category. Constrained by <code>TagCategoryChoices</code> in the spec (see [[#tagcategorychoices-values}}
{{Field|model=Tagging|section=Display & classification|name=priority|type=IntegerField|notes=<code>default=100</code>. Ordering weight}}
{{Field|model=Tagging|section=Display & classification|name=metadata|type=JSONField|notes=<code>default=None</code>, nullable. Shape defined by <code>TagConfigMetadata</code>: <code>{ color: str?, icon: str? }</code> (see [[#tagconfigmetadata-shape-of-metadata}}
|}

=== Tree structure & caches ===

<code>TagConfig</code> is self-referential — tags form a tree, and denormalized caches are rebuilt on insert to avoid recursive joins (the same pattern as [[References/Organization|<code>Organization</code>]]). These fields are platform-maintained and never writable through the create/update specs.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=Tagging|section=Tree structure & caches|name=parent|type=FK → self|notes=<code>CASCADE</code>, nullable. <code>related_name="children"</code>. Null parent means a root tag}}
{{Field|model=Tagging|section=Tree structure & caches|name=root_tag_config|type=FK → self|notes=<code>CASCADE</code>, nullable. <code>related_name="root"</code>. Top of the tree, derived on save}}
{{Field|model=Tagging|section=Tree structure & caches|name=has_children|type=BooleanField|notes=<code>default=False</code>. Flipped to <code>True</code> on the parent when a child is created}}
{{Field|model=Tagging|section=Tree structure & caches|name=level_cache|type=IntegerField|notes=<code>default=0</code>. Depth in the tree (<code>parent.level_cache + 1</code>)}}
{{Field|model=Tagging|section=Tree structure & caches|name=parent_cache|type=ArrayField[int]|notes=<code>default=list</code>. Full ancestor id chain (<code>parent.parent_cache + [parent.id]</code>)}}
{{Field|model=Tagging|section=Tree structure & caches|name=cached_parent_json|type=JSONField|notes=<code>default=dict</code>. Materialized parent record with a <code>cache_expiry</code>; rebuilt after <code>cache_expiry_days</code> (15). Shape: <code>{ id, display, description, category, parent (nested same shape), level_cache, cache_expiry }</code>}}
|}

== Enums ==

=== <code>TagCategoryChoices</code> values ===

<code>category</code> binds to this enum in every spec (<code>str</code> values).

{| class="wikitable"
|-
! Value
|-
| <code>diet</code>
|-
| <code>drug</code>
|-
| <code>lab</code>
|-
| <code>admin</code>
|-
| <code>contact</code>
|-
| <code>clinical</code>
|-
| <code>behavioral</code>
|-
| <code>research</code>
|-
| <code>advance_directive</code>
|-
| <code>safety</code>
|}

=== <code>TagResource</code> values ===

<code>resource</code> binds to this enum in <code>TagConfigWriteSpec</code> (set only on create; the read specs surface it as a plain <code>str</code>).

{| class="wikitable"
|-
! Value
|-
| <code>encounter</code>
|-
| <code>activity_definition</code>
|-
| <code>service_request</code>
|-
| <code>charge_item</code>
|-
| <code>charge_item_definition</code>
|-
| <code>patient</code>
|-
| <code>token_booking</code>
|-
| <code>medication_request_prescription</code>
|-
| <code>supply_request_order</code>
|-
| <code>supply_delivery_order</code>
|-
| <code>account</code>
|}

=== <code>TagStatus</code> values ===

<code>status</code> binds to this enum in every spec (<code>str</code> values).

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>active</code>
| Tag is available for use
|-
| <code>archived</code>
| Tag retired; retained for historical references
|}

== Nested specs (shape of JSON fields) ==

=== <code>TagConfigMetadata</code> (shape of <code>metadata</code>) ===

Gives the opaque <code>metadata</code> <code>JSONField</code> a real structure. A plain Pydantic <code>BaseModel</code>, not an <code>EMRResource</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=Tagging|section=TagConfigMetadata (shape of metadata)|name=color|type=str | None|notes=no}}
{{Field|model=Tagging|section=TagConfigMetadata (shape of metadata)|name=icon|type=str | None|notes=no}}
|}

== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>care/emr/resources/base.py</code>), which supplies <code>serialize</code> (DB object → spec) and <code>de_serialize</code> (spec → DB object) plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks. <code>__exclude__</code> on the base spec keeps the FK fields (<code>facility</code>, <code>facility_organization</code>, <code>organization</code>, <code>parent</code>) out of the generic field copy so each spec can resolve them explicitly.

{| class="wikitable"
|-
! Spec class
! Role
! Notes
|-
| <code>TagConfigBaseSpec</code>
| shared
| <code>__model__ = TagConfig</code>; <code>__exclude__ = [facility, facility_organization, organization, parent]</code>. Fields: <code>id</code> (<code>UUID4?</code>), <code>display</code>, <code>category</code> (<code>TagCategoryChoices</code>), <code>description</code> (<code>str | None</code>), <code>priority</code> (<code>int = 100</code>), <code>status</code> (<code>TagStatus</code>), <code>metadata</code> (<code>TagConfigMetadata?</code>)
|-
| <code>TagConfigWriteSpec</code>
| write · create
| Base + <code>facility?</code>, <code>facility_organization?</code>, <code>organization?</code>, <code>parent?</code> (all <code>UUID4</code>), <code>resource</code> (<code>TagResource</code>, required). Runs two <code>model_validator(after)</code> checks and resolves FKs in <code>perform_extra_deserialization</code>
|-
| <code>TagConfigUpdateSpec</code>
| write · update
| Base + <code>facility_organization?</code>, <code>organization?</code> (<code>UUID4</code>). Cannot change <code>facility</code>, <code>parent</code>, or <code>resource</code>. Resolves <code>organization</code>/<code>facility_organization</code> in <code>perform_extra_deserialization</code> (facility organization scoped to <code>obj.facility</code>)
|-
| <code>TagConfigReadSpec</code>
| read · list
| <code>@cacheable</code>. Base + <code>level_cache</code> (<code>int = 0</code>), <code>system_generated</code> (<code>bool</code>), <code>has_children</code> (<code>bool</code>), <code>parent</code> (<code>dict | None</code>), <code>resource</code> (<code>str</code>), <code>facility</code> (<code>dict | None</code>). Inlines parent via <code>get_parent_json()</code> and a <code>FacilityBareMinimumSpec</code> for <code>facility</code>
|-
| <code>TagConfigRetrieveSpec</code>
| read · detail
| Extends read spec + <code>created_by</code> (<code>dict</code>), <code>updated_by</code> (<code>dict</code>), <code>facility_organization</code> (<code>dict | None</code>), <code>organization</code> (<code>dict | None</code>). Adds audit users and full org/facility-org serialization
|}

=== Write-spec validation (<code>TagConfigWriteSpec</code>) ===

Two <code>@model_validator(mode="after")</code> checks run before deserialization:

* <code>validate_exists</code>:
** If <code>facility</code> is set, it must exist; if <code>facility_organization</code> is also set it must belong to that facility, else <code>ValidationError("Facility Organization not found")</code>.
** If <code>organization</code> is set, it must exist, else <code>ValidationError("Organization not found")</code>.
** If <code>parent</code> is set, a <code>TagConfig</code> with that <code>external_id</code> '''and the same <code>resource</code>''' must exist (and, when <code>facility</code> is set, belong to that facility), else <code>ValueError("Parent tag config not found")</code>.
* <code>validate_organizations</code>: a <code>facility_organization</code> without a <code>facility</code> is rejected — <code>ValueError("Facility Organization not allowed in instance level tag configs")</code>.

=== Server-maintained behaviour ===

* <code>TagConfigWriteSpec.perform_extra_deserialization</code> resolves <code>parent</code>, <code>organization</code>, and <code>facility</code> (plus <code>facility_organization</code> scoped to the resolved facility) from their <code>external_id</code>s onto the model instance; <code>parent</code> is explicitly set to <code>None</code> when absent.
* <code>TagConfigReadSpec.perform_extra_serialization</code> sets <code>id = external_id</code>, inlines the parent record via <code>obj.get_parent_json()</code> (only when non-empty), and serializes <code>facility</code> with <code>FacilityBareMinimumSpec</code> (<code>{ id, name }</code>).
* <code>TagConfigRetrieveSpec.perform_extra_serialization</code> calls the read-spec hook, then <code>serialize_audit_users</code> (populates <code>created_by</code>/<code>updated_by</code> from cache) and serializes <code>facility_organization</code> / <code>organization</code> with their full read specs.
* Tree caches (<code>level_cache</code>, <code>parent_cache</code>, <code>root_tag_config</code>, <code>has_children</code>) are populated by the model's <code>set_tag_config_cache()</code> on insert — never accepted from clients.
* <code>system_generated</code> is declared on <code>TagConfigReadSpec</code> but is not a field on the current <code>TagConfig</code> model (nor on <code>EMRBaseModel</code>). The generic <code>serialize</code> only copies model fields, so it is not populated from storage unless something else provides it. Treat it as a read-only flag and verify against the live model before relying on it.

=== Cache invalidation ===

A <code>post_save</code> signal connects <code>invalidate_tag_config_cache</code> to <code>TagConfig</code>. Every save does three things.

# Invalidates the tag's own <code>TagConfigReadSpec</code> cache and resets <code>cached_parent_json = {}</code>.
# Invalidates all descendants (rows whose <code>parent_cache</code> overlaps the tag id) — they embed parent data via <code>get_parent_json()</code>.
# Invalidates the parent's cache (its <code>has_children</code> may have changed).

== Methods & save behaviour ==

=== <code>set_tag_config_cache()</code> ===

When a <code>parent</code> is set, recomputes <code>parent_cache</code> (<code>parent.parent_cache + [parent.id]</code>) and <code>level_cache</code> (<code>parent.level_cache + 1</code>), then derives <code>root_tag_config</code> from the parent — the parent itself if the parent is a root, otherwise the parent's <code>root_tag_config</code>. If the parent had no children, it flips <code>parent.has_children = True</code>, persisting only that field. Finishes with <code>super().save()</code>.

=== <code>get_parent_json()</code> ===

Returns <code>cached_parent_json</code> when it is present and its <code>cache_expiry</code> is still in the future. Otherwise it recursively rebuilds the nested parent record (<code>id</code> = parent <code>external_id</code>, <code>display</code>, <code>description</code>, <code>category</code>, nested <code>parent</code>, <code>level_cache</code>), stamps a fresh expiry (<code>cache_expiry_days = 15</code>), persists <code>cached_parent_json</code>, and returns it. Returns <code>{}</code> for root tags.

=== <code>save()</code> side effects ===

On insert (no <code>id</code> yet), the base <code>save()</code> runs first, then <code>set_tag_config_cache()</code> populates the tree caches in a second write pass. On update, <code>save()</code> persists normally without recomputing caches. Both paths trigger the <code>post_save</code> cache-invalidation signal described above.

== API integration notes ==

The REST API exposes only the definitions. Applied tags are stored as integer ID arrays on each tagged resource (e.g. <code>Patient.instance_tags</code>/<code>facility_tags</code>, <code>Encounter.tags</code>), not as join rows.

Each operation maps to one spec:

* Create — <code>TagConfigWriteSpec</code>. Sets <code>resource</code>, the scope FKs, and <code>parent</code>. <code>resource</code> must match a [[#tagresource-values|<code>TagResource</code>]] value.
* Update — <code>TagConfigUpdateSpec</code>. Reassigns org/facility-org only, plus the shared display/category/status/metadata fields; <code>facility</code>, <code>parent</code>, and <code>resource</code> are fixed.
* List — <code>TagConfigReadSpec</code>. Detail — <code>TagConfigRetrieveSpec</code>.

<code>metadata</code> carries display hints (<code>color</code>, <code>icon</code>) without a schema migration, shaped by <code>TagConfigMetadata</code>.

{{Related}}

References/Tagging - Revision history

Admin: Add Navbox platform (via update-page on MediaWiki MCP Server)

Admin: OHC identity seed