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

2026-07-06T04:02:20Z

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

← Older revision		Revision as of 09:32, 6 July 2026
Line 343:		Line 343:
	* Treat <code>is_system_defined</code> value sets as read-only — they are platform-maintained. Author your own for local terminology; the <code>system-</code> slug prefix is reserved for system value sets.		* Treat <code>is_system_defined</code> value sets as read-only — they are platform-maintained. Author your own for local terminology; the <code>system-</code> slug prefix is reserved for system value sets.
	* <code>favorite_codes</code> (via <code>UserValueSetPreference</code>) and recent views (via <code>RecentViewsManager</code>/Redis) are per-user personalization, not part of the value set definition.		* <code>favorite_codes</code> (via <code>UserValueSetPreference</code>) and recent views (via <code>RecentViewsManager</code>/Redis) are per-user personalization, not part of the value set definition.

			{{Navbox definitions}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:44:54Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Value Set
|order=3
|introduced=3.0
|model=ValueSet
|reference=References/Base models & conventions
}}

A <code>ValueSet</code> is a FHIR-aligned composition of coded concepts drawn from one or more code systems. Reach for one when a [[References/Questionnaire|questionnaire]] needs to constrain a coded answer to a fixed set of options.

The Django model is only storage — <code>compose</code> is an opaque <code>JSONField</code>. The structure that matters (include/exclude clauses, filters, the status enum, validation, and the read/write API schemas) lives in the Pydantic resource specs, covered alongside the model here.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/valueset.py <code>care/emr/models/valueset.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/valueset/spec.py <code>care/emr/resources/valueset/spec.py</code>]
* Compose schema: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/common/valueset.py <code>care/emr/resources/common/valueset.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ValueSet</code>
| A named, FHIR-compatible composition of codes from one or more code systems
|-
| <code>UserValueSetPreference</code>
| Stores a user's favorited codes within a value set
|-
| <code>RecentViewsManager</code>
| Redis-backed helper for tracking a user's recently used codes (not a database model)
|}

<code>ValueSet</code> and <code>UserValueSetPreference</code> extend [[References/Base models & conventions|<code>EMRBaseModel</code>]], the shared Care EMR base that supplies <code>external_id</code>, audit fields, <code>history</code>/<code>meta</code> JSON, and soft-delete semantics.

== <code>ValueSet</code> fields ==

A value set stores rules, not a flat list of codes: a <code>compose</code> object of include/exclude clauses against code systems. Members resolve in real time against terminology servers when the value set is searched or a code is looked up.

{| class="wikitable"
|-
! Field
! Model type
! Spec type
! Required
! Default
! Notes
|-
| <code>slug</code>
| <code>SlugField(255)</code>
| <code>SlugType</code>
| yes
| —
| <code>unique</code>, indexed. Public identifier. Spec constrains to min 5 / max 50 chars, URL-safe (<code>^[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]$</code>); must start and end alphanumeric. Uniqueness re-checked in spec; <code>system-</code> prefix reserved (see validation)
|-
| <code>name</code>
| <code>CharField(255)</code>
| <code>str</code>
| yes
| —
| Display name. Spec rejects blank/whitespace-only and strips surrounding whitespace
|-
| <code>description</code>
| <code>TextField</code>
| <code>str</code>
| yes (in spec)
| <code>""</code> (model)
| Free text. The model defaults to an empty string; the spec requires the field present
|-
| <code>compose</code>
| <code>JSONField</code>
| <code>ValueSetCompose</code>
| yes
| <code>dict</code>
| Composition rules — structured <code>include</code>/<code>exclude</code> clauses (see [[#compose-shape
|-
| <code>status</code>
| <code>CharField(255)</code>
| <code>ValueSetStatusOptions</code>
| yes
| —
| Publication status enum (see [[#valuesetstatusoptions-values
|-
| <code>is_system_defined</code>
| <code>BooleanField</code>
| <code>bool</code>
| no
| <code>False</code>
| Marks value sets shipped and maintained by the platform rather than authored by a deployment
|}

=== <code>ValueSetStatusOptions</code> values ===

A <code>str</code> enum in <code>resources/valueset/spec.py</code>. The model column is a free <code>CharField</code>; the spec restricts writes to these four values.

{| class="wikitable"
|-
! Value
! Meaning
|-
| <code>draft</code>
| Authored, not yet in use
|-
| <code>active</code>
| Published and usable
|-
| <code>retired</code>
| No longer recommended for use
|-
| <code>unknown</code>
| Status not known
|}

=== <code>compose</code> shape ===

<code>compose</code> holds a <code>ValueSetCompose</code> structure (<code>care.emr.resources.common.valueset</code>). Each clause targets a <code>system</code> (a code system URI) and selects concepts directly or through filters. Every nested model sets <code>extra="forbid"</code>, so unknown keys are rejected.

==== <code>ValueSetCompose</code> ====

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=ValueSet|section=ValueSetCompose|name=id|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetCompose|name=include|type=list[ValueSetInclude]|notes=yes}}
{{Field|model=ValueSet|section=ValueSetCompose|name=exclude|type=list[ValueSetInclude] | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetCompose|name=property|type=list[str] | None|notes=no}}
|}

==== <code>ValueSetInclude</code> (used for both <code>include</code> and <code>exclude</code>) ====

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=ValueSet|section=ValueSetInclude (used for both include and exclude)|name=id|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetInclude (used for both include and exclude)|name=system|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetInclude (used for both include and exclude)|name=version|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetInclude (used for both include and exclude)|name=concept|type=list[ValueSetConcept] | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetInclude (used for both include and exclude)|name=filter|type=list[ValueSetFilter] | None|notes=no}}
|}

A clause may set <code>concept</code> or <code>filter</code>, not both — enforced by <code>check_concept_or_filter</code> (mode=after).

==== <code>ValueSetConcept</code> ====

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

==== <code>ValueSetFilter</code> ====

{| class="wikitable"
|-
! Field
! Type
! Required
! Default
! Notes
{{Field|model=ValueSet|section=ValueSetFilter|name=id|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetFilter|name=property|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetFilter|name=op|type=str | None|notes=no}}
{{Field|model=ValueSet|section=ValueSetFilter|name=value|type=str | None|notes=no}}
|}

===== <code>op</code> allowed values =====

<code>validate_op</code> rejects anything outside this set: <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>.

<syntaxhighlight lang="text">compose:
include:
- system: <code system uri>
version: <optional system version>
concept: [ { code, display } ] # pin concepts (mutually exclusive with filter)
filter: [ { property, op, value } ] # rule-based selection
exclude:
- ... same ValueSetInclude shape ...
property: [ <property names to return> ]</syntaxhighlight>
<code>create_composition()</code> regroups these clauses by <code>system</code> into <code>{ <system>: {include: [...], exclude: [...]} }</code> so each system can be queried independently, dumping each clause with <code>exclude_defaults=True</code>.

<blockquote>Note: a second, simpler <code>ValueSet</code> BaseModel (<code>name</code>, <code>status</code>, <code>compose</code>) plus <code>ValueSetConcept</code>/<code>ValueSetFilter</code>/<code>ValueSetInclude</code>/<code>ValueSetCompose</code> all live in <code>resources/common/valueset.py</code>. The persisted/API resource model is <code>ValueSetBaseSpec</code> in <code>resources/valueset/spec.py</code>, which reuses the same <code>ValueSetCompose</code>.
</blockquote>
== Resource specs (API schema) ==

Every spec extends <code>EMRResource</code> (<code>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). <code>ValueSet</code> leaves <code>__store_metadata__</code> unset, so spec fields map directly to model columns — there is no <code>meta</code> bag.

{| class="wikitable"
|-
! Spec class
! Role
! Fields exposed
|-
| <code>ValueSetBaseSpec</code>
| shared base (<code>__model__ = ValueSet</code>)
| <code>id</code> (UUID4), <code>slug</code>, <code>name</code>, <code>description</code>, <code>compose</code>, <code>status</code>, <code>is_system_defined</code>
|-
| <code>ValueSetSpec</code>
| write · create & update
| inherits base + validation + <code>perform_extra_deserialization</code>
|-
| <code>ValueSetReadSpec</code>
| read · list & detail
| inherits base + <code>created_by</code>, <code>updated_by</code> (dicts)
|}

=== Validation (<code>ValueSetSpec</code>) ===

{| class="wikitable"
|-
! Rule
! Where
! Behaviour
|-
| Name not empty
| <code>validate_name</code> (field)
| Rejects blank/whitespace-only; strips surrounding whitespace
|-
| Slug unique
| <code>validate_slug</code> (field)
| Queries existing <code>ValueSet</code> rows; on update, excludes the current object (via <code>context["object"].id</code> when <code>context["is_update"]</code>); otherwise raises <code>"Slug must be unique"</code>
|-
| Reserved slug
| <code>validate_slug_system</code> (model, after)
| If the value set is not <code>is_system_defined</code> and the slug contains <code>"system-"</code>, raises <code>"Cannot create valueset with system like slug"</code>
|-
| Slug format
| <code>SlugType</code>
| min 5 / max 50 chars, URL-safe, alphanumeric start/end
|-
| <code>op</code> allowlist
| <code>ValueSetFilter.validate_op</code>
| See [[#op-allowed-values
|-
| <code>concept</code> xor <code>filter</code>
| <code>ValueSetInclude.check_concept_or_filter</code>
| Both present → error
|}

=== Server-side serialization hooks ===

{| class="wikitable"
|-
! Hook
! Spec
! Effect
|-
| <code>perform_extra_deserialization(is_update, obj)</code>
| <code>ValueSetSpec</code>
| On write, sets <code>obj.compose = self.compose.model_dump(exclude_defaults=True, exclude_none=True)</code>, normalizing the JSON stored in the model
|-
| <code>perform_extra_serialization(mapping, obj)</code>
| <code>ValueSetReadSpec</code>
| On read, sets <code>mapping["id"] = obj.external_id</code> and populates <code>created_by</code> / <code>updated_by</code> via <code>serialize_audit_users</code>
|}

<code>ValueSetSpec.model_rebuild()</code> runs at module load so the forward reference to <code>ValueSetCompose</code> resolves.

== Related models ==

=== <code>UserValueSetPreference</code> ===

Holds the codes a single user has favorited within one value set.

<syntaxhighlight lang="text">user → FK users.User (CASCADE)
valueset → FK emr.ValueSet (CASCADE)
favorite_codes → JSONField (default=list)</syntaxhighlight>
<code>unique_together = ("user", "valueset")</code> enforces one preference row per user per value set. The class constant <code>MAX_FAVORITES</code> (default <code>50</code>, overridable via <code>settings.MAX_FAVORITES_FOR_VALUESET</code>) caps how many codes a user may favorite.

=== <code>RecentViewsManager</code> ===

A classmethod-only helper, not a database model. It tracks a user's recently viewed codes in a Redis list (one per <code>cache_key</code>) so pickers can surface recent codes alongside favorites.

{| class="wikitable"
|-
! Member
! Behaviour
|-
| <code>get_client()</code>
| Lazily opens the <code>"default"</code> Redis connection
|-
| <code>get_recent_views(cache_key)</code>
| Returns the decoded list of recent code objects
|-
| <code>add_recent_view(cache_key, code_obj)</code>
| De-dupes by <code>code</code> (no-op if <code>code</code> missing), <code>LPUSH</code>es the entry, then <code>LTRIM</code>s to <code>MAX_RECENT_VIEW</code>
|-
| <code>remove_recent_view(cache_key, code_obj)</code>
| Removes any list entry matching <code>code</code> (no-op if <code>code</code> missing)
|-
| <code>clear_recent_views(cache_key)</code>
| Deletes the whole list
|-
| <code>_remove_by_code(cache_key, code)</code>
| Internal: scans the list and <code>LREM</code>s matching entries; malformed JSON entries are skipped
|}

<code>MAX_RECENT_VIEW</code> defaults to <code>20</code> (overridable via <code>settings.MAX_RECENT_VIEW_FOR_VALUESET</code>). Entries are JSON-encoded; malformed ones are skipped on read and remove.

== Methods & save behaviour ==

<code>ValueSet</code> does not override <code>save()</code>/<code>delete()</code> — soft-delete is inherited from the base. Its methods drive terminology resolution:

* <code>create_composition()</code> — converts <code>compose</code> (a dict or <code>ValueSetCompose</code>) into a per-system map of <code>include</code>/<code>exclude</code> clauses, dumping each clause with <code>exclude_defaults=True</code>.
* <code>search(search="", count=10, display_language=None)</code> — runs <code>ValueSetResource().filter(...).search()</code> for each system in the composition (optionally filtered by <code>display_language</code>) and concatenates the results. Codes are fetched from the terminology server at request time; nothing is materialized into the value set.
* <code>lookup(code)</code> — checks whether <code>code</code> is a member by running <code>ValueSetResource().filter(...).lookup(code)</code> against each system, returning <code>True</code> if any system matches.

Membership resolves live, so editing <code>compose</code> immediately changes which codes the value set yields. There is no expansion or cache to rebuild.

== API integration notes ==

* The REST API aligns with the FHIR <code>ValueSet</code> resource. Writes go through <code>ValueSetSpec</code>, reads through <code>ValueSetReadSpec</code>; <code>search</code> powers code pickers and <code>lookup</code> validates submitted codes.
* The model column <code>compose</code> is opaque JSON, so always write through the <code>ValueSetCompose</code> schema (clauses, filters, the <code>op</code> allowlist, <code>concept</code> xor <code>filter</code>). <code>perform_extra_deserialization</code> re-dumps it with <code>exclude_defaults</code>/<code>exclude_none</code> to keep stored JSON normalized.
* Composition rules are stored, not expanded code lists. Members are queried in real time from terminology servers, so results shift as upstream systems change.
* Treat <code>is_system_defined</code> value sets as read-only — they are platform-maintained. Author your own for local terminology; the <code>system-</code> slug prefix is reserved for system value sets.
* <code>favorite_codes</code> (via <code>UserValueSetPreference</code>) and recent views (via <code>RecentViewsManager</code>/Redis) are per-user personalization, not part of the value set definition.

{{Related}}

References/Value Set - Revision history

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

Admin: OHC identity seed