Admin: OHC identity seed

2026-07-04T22:45:12Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=foundation
|title=Base models & conventions
|order=1
|introduced=3.0
|model=BaseModels&Conventions
|reference=References/Charge Item Definition
}}

Every Care EMR resource inherits a shared base that supplies opaque IDs, audit fields, soft-delete, history, slugs, and feature flags. A resource author writes domain fields and validation; the base handles the rest. It spans two layers:

* '''Storage layer''' — abstract Django models in <code>care/emr/models</code> and <code>care/utils/models</code>. Several of their columns are opaque <code>JSONField</code>s whose structure lives elsewhere; the model alone won't tell you what goes inside them.
* '''API layer''' — Pydantic resource specs built on <code>EMRResource</code> (<code>care/emr/resources/base.py</code>). These define enums, field validation, the read/write schemas, and the structured shapes that fill those JSON columns via nested specs. The structured types in <code>care/emr/resources/common/</code> are reused across nearly every resource.

Come here for the rules a resource gets for free: the soft-delete contract, what <code>serialize</code>/<code>de_serialize</code> do, how write and read schemas diverge, and the common spec types behind the JSON fields. Concrete resources such as [[References/Patient]] inherit a storage base and define their own specs on top of <code>EMRResource</code>.

'''Source:''' [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/base.py <code>care/emr/models/base.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/utils/models/base.py <code>care/utils/models/base.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/base.py <code>care/emr/resources/base.py</code>], [<nowiki/>https://github.com/ohcnetwork/care/tree/develop/care/emr/resources/common <code>care/emr/resources/common/</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Layer
! Purpose
|-
| <code>BaseModel</code>
| storage
| Lowest-level abstract base — opaque <code>external_id</code>, timestamps, and soft-delete
|-
| <code>BaseManager</code>
| storage
| Default manager that hides soft-deleted rows
|-
| <code>BaseFlag</code>
| storage
| Abstract base for feature-flag tables with cache-backed lookups
|-
| <code>EMRBaseModel</code>
| storage
| Standard base for EMR resources — adds audit <code>created_by</code>/<code>updated_by</code>, <code>history</code>, and <code>meta</code>
|-
| <code>SlugBaseModel</code>
| storage
| EMR base that adds facility-scoped or instance-scoped slug helpers
|-
| <code>EMRResource</code>
| API
| Pydantic base for all resource specs — <code>serialize</code> / <code>de_serialize</code> between DB objects and API schemas
|}

All five storage models are <code>abstract = True</code> — none owns a database table. A concrete resource model inherits one and contributes its own columns.

The storage models inherit in one chain:

<syntaxhighlight lang="text">models.Model
└─ BaseModel (care/utils/models/base.py)
├─ BaseFlag (care/utils/models/base.py)
└─ EMRBaseModel (care/emr/models/base.py)
└─ SlugBaseModel</syntaxhighlight>
The API specs form a parallel hierarchy under <code>pydantic.BaseModel</code>:

<syntaxhighlight lang="text">pydantic.BaseModel
└─ EMRResource (care/emr/resources/base.py)
└─ <Resource>SpecBase / <Resource>CreateSpec / ...ReadSpec / ...RetrieveSpec</syntaxhighlight>

-----

== Storage layer ==

=== <code>BaseModel</code> fields ===

The root abstract model. Every other base — and so every persisted Care resource — carries these four columns.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=BaseModels&Conventions|section=BaseModel fields|name=external_id|type=UUIDField|notes=yes}}
{{Field|model=BaseModels&Conventions|section=BaseModel fields|name=created_date|type=DateTimeField|notes=no}}
{{Field|model=BaseModels&Conventions|section=BaseModel fields|name=modified_date|type=DateTimeField|notes=no}}
{{Field|model=BaseModels&Conventions|section=BaseModel fields|name=deleted|type=BooleanField|notes=yes}}
|}

<code>objects</code> is overridden to a [[#basemanager|<code>BaseManager</code>]], so the default queryset returns only live rows.

==== Soft delete ====

<code>BaseModel.delete()</code> issues no SQL <code>DELETE</code>. It flips the flag and persists only that column:

<syntaxhighlight lang="python">def delete(self, *args):
self.deleted = True
self.save(update_fields=["deleted"])</syntaxhighlight>
Rows stay put for audit and referential integrity. To reach deleted rows, bypass the default manager — for example via <code>Model._base_manager</code> or an unfiltered queryset.

=== <code>EMRBaseModel</code> fields ===

The standard base for EMR resource models. On top of the <code>BaseModel</code> columns it adds audit, history, and metadata:

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=BaseModels&Conventions|section=EMRBaseModel fields|name=history|type=JSONField|notes=no}}
{{Field|model=BaseModels&Conventions|section=EMRBaseModel fields|name=meta|type=JSONField|notes=no}}
{{Field|model=BaseModels&Conventions|section=EMRBaseModel fields|name=created_by|type=FK → users.User|notes=no}}
{{Field|model=BaseModels&Conventions|section=EMRBaseModel fields|name=updated_by|type=FK → users.User|notes=no}}
|}

The <code>%(app_label)s_%(class)s_…</code> <code>related_name</code> template lets every concrete subclass reuse the same FK definitions without reverse-accessor collisions.

=== <code>SlugBaseModel</code> helpers ===

Extends <code>EMRBaseModel</code> for resources that expose a human-readable, scoped slug — value sets and definitions, for instance. It adds no columns of its own; concrete subclasses supply their own <code>slug</code> and, when facility-scoped, <code>facility</code> fields. It sets the class flag <code>FACILITY_SCOPED = True</code>.

{| class="wikitable"
|-
! Method
! Behaviour
|-
| <code>calculate_slug_from_facility(facility_external_id, slug)</code>
| Class helper → <code>f-<facility_external_id>-<slug></code>
|-
| <code>calculate_slug_from_instance(slug)</code>
| Class helper → <code>i-<slug></code>
|-
| <code>calculate_slug()</code>
| Instance helper — facility-scoped form when <code>FACILITY_SCOPED</code> and <code>facility</code> are set, otherwise instance-scoped
|-
| <code>parse_slug(slug)</code>
| Reverses the encoding; returns <code>{facility, slug_value}</code> for <code>f-</code> slugs or <code>{slug_value}</code> for <code>i-</code> slugs; raises <code>ValueError</code> on invalid input
|}

Slug encoding:

<syntaxhighlight lang="text">facility-scoped: f-<facility external_id (36-char UUID)>-<slug>
instance-scoped: i-<slug></syntaxhighlight>
<code>parse_slug</code> reads the facility segment as <code>slug[2:38]</code> (36 chars), validates it as a UUID, takes <code>slug[39:]</code> as the slug value, and rejects any slug of length ≤ 2.

-----

== Related models ==

=== <code>BaseManager</code> ===

The default manager set as <code>objects</code> on <code>BaseModel</code>. Every query through <code>Model.objects</code> is implicitly scoped to <code>deleted=False</code>:

<syntaxhighlight lang="python">def get_queryset(self):
return super().get_queryset().filter(deleted=False)</syntaxhighlight>
=== <code>BaseFlag</code> ===

Abstract base for per-entity feature-flag tables (facility or organization flags, for example). It extends <code>BaseModel</code>, stores one validated flag name, and serves all lookups from cache.

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=BaseModels&Conventions|section=BaseFlag|name=flag|type=CharField(max_length=1024)|notes=Flag name, validated against <code>FlagRegistry</code> for the subclass's <code>flag_type</code>}}
|}

Subclasses configure these class attributes:

{| class="wikitable"
|-
! Attribute
! Purpose
|-
| <code>cache_key_template</code>
| Cache key for a single <code>(entity_id, flag_name)</code> pair
|-
| <code>all_flags_cache_key_template</code>
| Cache key for all flags of one entity
|-
| <code>flag_type</code>
| Flag category validated against <code>FlagRegistry</code>
|-
| <code>entity_field_name</code>
| Name of the FK field pointing at the owning entity
|}

Helper properties and classmethods:

{| class="wikitable"
|-
! Member
! Behaviour
|-
| <code>entity</code>
| Resolves the related entity via <code>entity_field_name</code>
|-
| <code>entity_id</code>
| Resolves <code><entity_field_name>_id</code> without a join
|-
| <code>validate_flag(flag_name)</code>
| Validates the name against <code>FlagRegistry</code> for <code>flag_type</code>
|-
| <code>check_entity_has_flag(entity_id, flag_name)</code>
| Cached <code>exists()</code> lookup (TTL 1 day)
|-
| <code>get_all_flags(entity_id)</code>
| Cached tuple of all flag names for an entity (TTL 1 day)
|}

-----

== API layer ==

=== <code>EMRResource</code> ===

The Pydantic base (<code>care/emr/resources/base.py</code>) that every resource spec extends. It moves data both ways between Django model instances and the API schema, and holds the serialization rules in one place.

{| class="wikitable"
|-
! Class attribute
! Default
! Role
|-
| <code>__model__</code>
| <code>None</code>
| The Django model the spec serializes to/from
|-
| <code>__exclude__</code>
| <code>[]</code>
| Field names skipped in both <code>serialize</code> and <code>de_serialize</code>
|-
| <code>__store_metadata__</code>
| <code>False</code>
| When <code>True</code>, spec fields that are not DB columns are read from / written to the model's <code>meta</code> JSON bag
|-
| <code>__version__</code>
| <code>0.1</code>
| Stamped onto every serialized object as <code>version</code>
|-
| <code>meta</code>
| <code>{}</code>
| Open metadata dict carried on the spec itself
|}

{| class="wikitable"
|-
! Method
! Direction
! Behaviour
|-
| <code>serialize(obj, user=None)</code>
| DB → API
| Builds a spec via <code>model_construct</code> from the DB object's columns; copies <code>meta</code> fields back out when <code>__store_metadata__</code>; calls <code>perform_extra_serialization</code> (always sets <code>mapping["id"] = obj.external_id</code>) and, when a <code>user</code> is passed, <code>perform_extra_user_serialization</code>; stamps <code>version</code>
|-
| <code>de_serialize(obj=None, partial=False)</code>
| API → DB
| Dumps the spec (<code>exclude_defaults=True</code>), writes mapped fields onto a new or existing model instance (skipping <code>__exclude__</code>, <code>id</code>, <code>external_id</code>), routes non-column fields into <code>meta</code> when <code>__store_metadata__</code>, then calls <code>perform_extra_deserialization(is_update, obj)</code>. <code>is_update</code> is <code>True</code> when an existing <code>obj</code> is supplied
|-
| <code>perform_extra_serialization(mapping, obj)</code>
| DB → API
| Hook for resolving derived/nested read fields; base sets <code>id</code>
|-
| <code>perform_extra_deserialization(is_update, obj)</code>
| API → DB
| Hook for server-side side effects on write (e.g. appending to <code>status_history</code>, resolving FKs from <code>external_id</code>, validating coded values against a value set)
|-
| <code>serialize_audit_users(mapping, obj)</code>
| DB → API
| Helper that fills <code>created_by</code> / <code>updated_by</code> from a cached <code>UserSpec</code>
|-
| <code>to_json()</code>
| —
| <code>model_dump(mode="json", exclude=["meta"])</code>
|-
| <code>get_database_mapping()</code>
| —
| Lists the model's non-FK column names, used to decide which spec fields map to columns
|}

Each concrete resource exposes a small set of specs built on <code>EMRResource</code>, named by convention:

{| class="wikitable"
|-
! Spec class
! Kind
! Role
|-
| <code><X>SpecBase</code>
| shared
| Common fields shared by the write/read specs
|-
| <code><X>CreateSpec</code>
| write · create
| Request body for POST; <code>de_serialize</code> builds a new model instance
|-
| <code><X>UpdateSpec</code>
| write · update
| Request body for PUT/PATCH; <code>de_serialize</code> updates an existing instance (<code>is_update=True</code>)
|-
| <code><X>ListSpec</code>
| read · list
| Lightweight response for list endpoints
|-
| <code><X>ReadSpec</code> / <code><X>RetrieveSpec</code>
| read · detail
| Full response for the detail endpoint (often resolving nested/coded fields in <code>perform_extra_serialization</code>)
|}

Coded fields commonly bind to a '''value set''' — a <code>system</code>/<code>code</code> allow-list. The resource spec declares the binding (e.g. via <code>json_schema_extra={"slug": "<valueset-slug>"}</code> on the field) and validates the submitted <code>Coding</code> against it in <code>perform_extra_deserialization</code>. Status fields commonly maintain a server-side <code>status_history</code> appended on create/update. Each resource page documents its exact bindings and side effects.

=== <code>PeriodSpec</code> ===

Defined alongside <code>EMRResource</code> in <code>base.py</code>. The validated period type used by write specs — distinct from the looser [[#period|<code>Period</code>]] read type in <code>common/</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Validation
|-
| <code>start</code>
| <code>datetime</code>
| no
| <code>None</code>
| must be timezone-aware
|-
| <code>end</code>
| <code>datetime</code>
| no
| <code>None</code>
| must be timezone-aware
|}

When both are set, <code>start</code> must be ≤ <code>end</code>. Naive datetimes are rejected with <code>"Start/End Date must be timezone aware"</code>.

=== <code>PhoneNumber</code> ===

An <code>Annotated</code> type exported from <code>base.py</code>: a phone string validated by <code>PhoneNumberValidator</code> with <code>number_format="E164"</code>, no default region, and no region restriction. Use it wherever a spec field accepts a phone number.

-----

== Shared common specs ==

<code>care/emr/resources/common/</code> holds the structured types reused across resources — the actual shapes behind many of the opaque <code>JSONField</code>s in the storage layer.

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

A single code from a code system. <code>model_config = extra="forbid"</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=BaseModels&Conventions|section=Coding|name=system|type=str|notes=no}}
{{Field|model=BaseModels&Conventions|section=Coding|name=version|type=str|notes=no}}
{{Field|model=BaseModels&Conventions|section=Coding|name=code|type=str|notes='''yes'''}}
{{Field|model=BaseModels&Conventions|section=Coding|name=display|type=str|notes=no}}
|}

=== <code>CodeableConcept</code> ===

A concept expressed as one or more codings plus free text. <code>extra="forbid"</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=BaseModels&Conventions|section=CodeableConcept|name=id|type=str|notes=no}}
{{Field|model=BaseModels&Conventions|section=CodeableConcept|name=coding|type=list[Coding]|notes=no}}
{{Field|model=BaseModels&Conventions|section=CodeableConcept|name=text|type=str | None|notes='''yes''' (field present)}}
|}

=== <code>Period</code> ===

The read/storage period shape — looser than <code>PeriodSpec</code>, with no timezone or ordering validation. <code>extra="forbid"</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
|-
| <code>id</code>
| <code>str</code>
| no
| <code>None</code>
|-
| <code>start</code>
| <code>datetime</code>
| no
| <code>None</code>
|-
| <code>end</code>
| <code>datetime</code>
| no
| <code>None</code>
|}

=== <code>Quantity</code> ===

A measured amount, optionally with coded units. <code>extra="forbid"</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=BaseModels&Conventions|section=Quantity|name=value|type=Decimal|notes=no}}
{{Field|model=BaseModels&Conventions|section=Quantity|name=unit|type=Coding|notes=no}}
{{Field|model=BaseModels&Conventions|section=Quantity|name=meta|type=dict|notes=no}}
{{Field|model=BaseModels&Conventions|section=Quantity|name=code|type=Coding|notes=no}}
|}

<code>Ratio</code> (same file) wraps two '''required''' <code>Quantity</code> values: <code>numerator</code> and <code>denominator</code>.

=== <code>ContactPoint</code> ===

A means of contact (phone, email, etc.). All three fields are '''required'''.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=BaseModels&Conventions|section=ContactPoint|name=system|type=ContactPointSystemChoices|notes=yes}}
{{Field|model=BaseModels&Conventions|section=ContactPoint|name=value|type=str|notes=yes}}
{{Field|model=BaseModels&Conventions|section=ContactPoint|name=use|type=ContactPointUseChoices|notes=yes}}
|}

==== <code>ContactPointSystemChoices</code> values ====

{| class="wikitable"
|-
! Value
|-
| <code>phone</code>
|-
| <code>fax</code>
|-
| <code>email</code>
|-
| <code>pager</code>
|-
| <code>url</code>
|-
| <code>sms</code>
|-
| <code>other</code>
|}

==== <code>ContactPointUseChoices</code> values ====

{| class="wikitable"
|-
! Value
|-
| <code>home</code>
|-
| <code>work</code>
|-
| <code>temp</code>
|-
| <code>old</code>
|-
| <code>mobile</code>
|}

=== <code>MonetaryComponent</code> and pricing types ===

Pricing line components used by billing resources (see [[References/Charge Item Definition]], [[References/Charge Item]]).

<code>MonetaryComponent</code>:

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=monetary_component_type|type=MonetaryComponentType|notes='''yes'''}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=code|type=Coding|notes=no}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=factor|type=Decimal|notes=no}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=amount|type=Decimal|notes=no}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=tax_included_amount|type=Decimal|notes=no}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=global_component|type=bool|notes=no}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponent and pricing types|name=conditions|type=list[EvaluatorConditionSpec]|notes=no}}
|}

Model validators enforce:

* <code>tax_included_amount</code> is only allowed when <code>monetary_component_type == base</code>.
* A <code>base</code> component must have no <code>conditions</code> and must set <code>amount</code>.
* <code>amount</code> and <code>factor</code> are mutually exclusive (not both).
* Either <code>amount</code> or <code>factor</code> must be present — unless <code>global_component</code> is set together with a <code>code</code>.

==== <code>MonetaryComponentType</code> values ====

{| class="wikitable"
|-
! Value
|-
| <code>base</code>
|-
| <code>surcharge</code>
|-
| <code>discount</code>
|-
| <code>tax</code>
|-
| <code>informational</code>
|}

<code>MonetaryComponentsWithoutBase</code> (a <code>RootModel</code> over <code>list[MonetaryComponent]</code>) adds two list-level rules: no duplicate <code>code.code</code> values across the list; and, when a base component declares <code>tax_included_amount</code>, the sum of tax-component amounts (or <code>base.amount * factor</code>) plus <code>tax_included_amount</code> must equal the base amount. <code>MonetaryComponents</code> extends it with one more: at most '''one''' <code>base</code> component.

<code>MonetaryComponentDefinition</code> extends <code>MonetaryComponent</code> for definition-time use: it adds a '''required''' <code>title: str</code>, disables the duplicate-code / amount-or-factor checks, and forbids a <code>base</code> component entirely.

<code>DiscountConfiguration</code>:

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=BaseModels&Conventions|section=MonetaryComponentType values|name=max_applicable|type=int|notes=<code>ge=0</code>}}
{{Field|model=BaseModels&Conventions|section=MonetaryComponentType values|name=applicability_order|type=DiscountApplicability|notes=enum below}}
|}

==== <code>DiscountApplicability</code> values ====

{| class="wikitable"
|-
! Value
|-
| <code>total_asc</code>
|-
| <code>total_desc</code>
|}

=== <code>EvaluatorConditionSpec</code> ===

A single condition evaluated against a registered metric — used inside <code>MonetaryComponent.conditions</code>.

{| class="wikitable"
|-
! Field
! Type
! Required
! Notes
{{Field|model=BaseModels&Conventions|section=EvaluatorConditionSpec|name=metric|type=str|notes=yes}}
{{Field|model=BaseModels&Conventions|section=EvaluatorConditionSpec|name=operation|type=str|notes=yes}}
{{Field|model=BaseModels&Conventions|section=EvaluatorConditionSpec|name=value|type=dict | str|notes=yes}}
|}

=== ValueSet definition types ===

The shapes used to ''define'' a value set (the FHIR <code>compose</code> structure), used by [[References/Value Set|ValueSet]].

* <code>ValueSet</code> — <code>name: str</code> (required), <code>status: str | None</code>, <code>compose: ValueSetCompose</code> (required).
* <code>ValueSetCompose</code> — <code>id</code>, <code>include: list[ValueSetInclude]</code> (required), <code>exclude: list[ValueSetInclude] | None</code>, <code>property: list[str] | None</code>.
* <code>ValueSetInclude</code> — <code>id</code>, <code>system</code>, <code>version</code>, <code>concept: list[ValueSetConcept] | None</code>, <code>filter: list[ValueSetFilter] | None</code>. '''<code>concept</code> and <code>filter</code> are mutually exclusive.'''
* <code>ValueSetConcept</code> — <code>id</code>, <code>code</code>, <code>display</code> (all optional).
* <code>ValueSetFilter</code> — <code>id</code>, <code>property</code>, <code>op</code>, <code>value</code>. <code>op</code> must be one of: <code>=</code>, <code>is-a</code>, <code>descendent-of</code>, <code>is-not-a</code>, <code>regex</code>, <code>in</code>, <code>not-in</code>, <code>generalizes</code>, <code>child-of</code>, <code>descendent-leaf</code>, <code>exists</code>.

All ValueSet types use <code>extra="forbid"</code>.

=== <code>MailTypeChoices</code> ===

Defined in <code>common/mail_type.py</code>.

{| class="wikitable"
|-
! Name
! Value
|-
| <code>create</code>
| <code>create_password</code>
|-
| <code>reset</code>
| <code>reset_password</code>
|}

-----

== Methods & save behaviour ==

* <code>BaseModel.delete()</code> soft-deletes: sets <code>deleted=True</code> and saves only that field, never a hard <code>DELETE</code>.
* <code>BaseFlag.save()</code> validates <code>flag</code> against <code>FlagRegistry</code>, then evicts the single-flag and all-flags cache entries for the entity before persisting, so cached lookups stay consistent.
* <code>BaseFlag.check_entity_has_flag</code> / <code>get_all_flags</code> populate those caches on read with a 1-day TTL (<code>FLAGS_CACHE_TTL = 60 * 60 * 24</code>).
* <code>SlugBaseModel</code> exposes slug encode/parse helpers but does not override <code>save()</code>; subclasses decide when to call <code>calculate_slug()</code>.
* <code>EMRResource.de_serialize</code> is where write-time side effects happen — subclasses override <code>perform_extra_deserialization</code> to append to status histories, resolve FKs from <code>external_id</code>, and validate coded fields against bound value sets.
* <code>cacheable(...)</code> (in <code>base.py</code>) is a decorator that marks a spec cacheable and wires a <code>post_save</code> signal to invalidate the per-instance serializer cache; <code>model_from_cache</code> then serves serialized specs from cache by <code>pk</code> / <code>id</code> / <code>external_id</code>.

== API integration notes ==

* <code>external_id</code> (UUID) is the identifier used across Care's REST API and FHIR resources; the integer primary key is internal and never exposed. <code>EMRResource.serialize</code> surfaces it as <code>id</code>, and <code>de_serialize</code> refuses to write <code>id</code> / <code>external_id</code> from request bodies.
* Deletes are soft — a resource removed through the API still exists in the database with <code>deleted=True</code>, hidden by the default manager.
* <code>history</code> is not returned by standard endpoints; every version (including migration-time changes) is stored flattened with its performer and served through a separate, on-request audit API.
* <code>meta</code> is the supported way to attach system metadata without a schema migration; specs with <code>__store_metadata__ = True</code> round-trip extra fields through it. <code>created_by</code> / <code>updated_by</code> are platform-maintained audit fields — clients must not set them directly.
* Periods sent on write (<code>PeriodSpec</code>) must be timezone-aware and ordered (<code>start ≤ end</code>); the read-side <code>Period</code> type does not enforce this.
* Feature-flag state (<code>BaseFlag</code> subclasses) is read through the cached classmethods, not queried row-by-row.

{{Related}}

References/Base models & conventions - Revision history

Admin: OHC identity seed