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

2026-07-06T04:02:53Z

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

← Older revision		Revision as of 09:32, 6 July 2026
Line 329:		Line 329:
	* <code>permitted_unit</code> codings follow UCUM, but Care never converts between units at display time — store data in the unit you intend to read.		* <code>permitted_unit</code> codings follow UCUM, but Care never converts between units at display time — store data in the unit you intend to read.
	* <code>convert_od_to_observation</code> (<code>observation.py</code>) builds an [[References/Observation\|<code>Observation</code>]] from a definition for a given encounter, carrying over <code>category</code> and <code>code</code> and defaulting <code>status</code> to <code>final</code>.		* <code>convert_od_to_observation</code> (<code>observation.py</code>) builds an [[References/Observation\|<code>Observation</code>]] from a definition for a given encounter, carrying over <code>category</code> and <code>code</code> and defaulting <code>status</code> to <code>final</code>.

			{{Navbox definitions}}

	{{Related}}		{{Related}}

Admin: OHC identity seed

2026-07-04T22:44:40Z

OHC identity seed

New page

{{Doc header
|type=reference
|domain=definitions
|title=Observation Definition
|order=4
|introduced=3.0
|model=ObservationDefinition
|reference=References/Base models & conventions
}}

An <code>ObservationDefinition</code> is master data describing ''how'' a particular observation is captured — its code, permitted data type, unit, method, body site, and (interpretation) reference ranges. You create one when you need a measurement collected consistently across forms; questionnaires reference it so the same observation (blood pressure, say) is recorded the same way everywhere, whether instance-wide or within a single facility. One observation code can back several definitions. The model loosely follows the [<nowiki/>https://build.fhir.org/observationdefinition.html FHIR ObservationDefinition] resource.

The Django model is only storage: <code>code</code>, <code>body_site</code>, <code>method</code>, <code>permitted_unit</code>, <code>component</code>, and <code>qualified_ranges</code> are opaque <code>JSONField</code>s. The shape you write against — enums, value-set bindings, read/write contracts — lives in the Pydantic resource specs (<code>care/emr/resources/observation_definition/spec.py</code>), built on the <code>EMRResource</code> base.

'''Source:'''

* Model: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/models/observation_definition.py <code>care/emr/models/observation_definition.py</code>]
* Resource spec: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/observation_definition/spec.py <code>care/emr/resources/observation_definition/spec.py</code>]
* Helper: [<nowiki/>https://github.com/ohcnetwork/care/blob/develop/care/emr/resources/observation_definition/observation.py <code>care/emr/resources/observation_definition/observation.py</code>]

== Models ==

{| class="wikitable"
|-
! Model
! Purpose
|-
| <code>ObservationDefinition</code>
| Master-data definition of how an observation is coded, typed, and measured
|}

<code>ObservationDefinition</code> extends [[References/Base models & conventions|<code>SlugBaseModel</code>]], which adds facility-scoped slug helpers on top of <code>EMRBaseModel</code>. From <code>EMRBaseModel</code> it inherits <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 the <code>history</code>/<code>meta</code> JSON fields.

== <code>ObservationDefinition</code> fields ==

=== Identity & scope ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ObservationDefinition|section=Identity & scope|name=facility|type=FK → Facility (PROTECT)|notes=Nullable, <code>default=None</code>. Set means the definition is scoped to that facility; <code>null</code> means instance-wide. Excluded from the base spec (<code>__exclude__ = ["facility"]</code>) and set server-side from the <code>facility</code> UUID on create}}
{{Field|model=ObservationDefinition|section=Identity & scope|name=version|type=IntegerField|notes=Defaults to <code>1</code>. Read-only — appears in <code>...ReadSpec</code> only, never accepted on write}}
{{Field|model=ObservationDefinition|section=Identity & scope|name=slug|type=CharField(255)|notes=Set server-side from <code>slug_value</code>, then namespaced. See [[#slug-behaviour}}
{{Field|model=ObservationDefinition|section=Identity & scope|name=title|type=CharField(1024)|notes=Required. Display name shown when authoring questionnaires; not the observation <code>code</code>}}
{{Field|model=ObservationDefinition|section=Identity & scope|name=status|type=CharField(255)|notes=Required. Lifecycle code from <code>ObservationStatusChoices</code> — see [[#status-values}}
{{Field|model=ObservationDefinition|section=Identity & scope|name=description|type=TextField|notes=Required. Natural-language (markdown) description}}
{{Field|model=ObservationDefinition|section=Identity & scope|name=derived_from_uri|type=TextField|notes=External URI this definition was derived from. Optional (<code>str | None</code>, default <code>None</code>)}}
|}

=== Coding & measurement ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ObservationDefinition|section=Coding & measurement|name=category|type=CharField(255)|notes=Nullable in the model, but '''required''' in the API as <code>ObservationCategoryChoices</code> — see [[#category-values}}
{{Field|model=ObservationDefinition|section=Coding & measurement|name=code|type=JSONField|notes=Required. What is being observed: a <code>Coding</code> bound to the <code>system-observation</code> value set (LOINC) — see [[#coding-shape}}
{{Field|model=ObservationDefinition|section=Coding & measurement|name=permitted_data_type|type=CharField(100)|notes=Required. <code>QuestionType</code> enum (questionnaire data types) — see [[#permitted-data-type-values}}
{{Field|model=ObservationDefinition|section=Coding & measurement|name=body_site|type=JSONField|notes=Nullable. <code>Coding</code> bound to the <code>system-body-site-observation</code> value set (SNOMED CT)}}
{{Field|model=ObservationDefinition|section=Coding & measurement|name=method|type=JSONField|notes=Nullable. <code>Coding</code> bound to the <code>system-collection-method</code> value set (SNOMED CT)}}
{{Field|model=ObservationDefinition|section=Coding & measurement|name=permitted_unit|type=JSONField|notes=Nullable. <code>Coding</code> bound to the <code>system-ucum-units</code> value set (UCUM). Care does not convert between units when displaying data}}
|}

=== Components & ranges ===

{| class="wikitable"
|-
! Field
! Type
! Notes
{{Field|model=ObservationDefinition|section=Components & ranges|name=component|type=JSONField|notes=Nullable. <code>list[ObservationDefinitionComponentSpec] | None</code>. Several measured values under one definition (systolic + diastolic, for example), each with its own <code>code</code>, <code>permitted_data_type</code>, <code>permitted_unit</code>, and <code>qualified_ranges</code> — see [[#observationdefinitioncomponentspec}}
{{Field|model=ObservationDefinition|section=Components & ranges|name=qualified_ranges|type=JSONField|notes=Model default <code>list</code>. '''Required''' in the API as <code>list[QualifiedRangeSpec]</code>, though it may be empty. Condition-dependent reference ranges / interpretations — see [[#qualifiedrangespec}}
|}

== Enum values ==

=== Status values ===

<code>ObservationStatusChoices</code> — bound to the <code>status</code> field.

{| class="wikitable"
|-
! Value
|-
| <code>draft</code>
|-
| <code>active</code>
|-
| <code>retired</code>
|-
| <code>unknown</code>
|}

=== Category values ===

<code>ObservationCategoryChoices</code> — bound to the <code>category</code> field.

{| class="wikitable"
|-
! Value
|-
| <code>social_history</code>
|-
| <code>vital_signs</code>
|-
| <code>imaging</code>
|-
| <code>laboratory</code>
|-
| <code>procedure</code>
|-
| <code>survey</code>
|-
| <code>exam</code>
|-
| <code>therapy</code>
|-
| <code>activity</code>
|}

=== Permitted data type values ===

<code>QuestionType</code> (from <code>questionnaire/spec.py</code>) — bound to <code>permitted_data_type</code> on both the definition and each component. <code>validate_question_type</code> rejects <code>group</code>, <code>display</code>, and <code>url</code> with "Cannot create a definition with this type".

{| class="wikitable"
|-
! Value
! Allowed for a definition
|-
| <code>group</code>
| No (rejected)
|-
| <code>boolean</code>
| Yes
|-
| <code>decimal</code>
| Yes
|-
| <code>integer</code>
| Yes
|-
| <code>string</code>
| Yes
|-
| <code>text</code>
| Yes
|-
| <code>display</code>
| No (rejected)
|-
| <code>date</code>
| Yes
|-
| <code>dateTime</code>
| Yes
|-
| <code>time</code>
| Yes
|-
| <code>choice</code>
| Yes
|-
| <code>url</code>
| No (rejected)
|-
| <code>quantity</code>
| Yes
|-
| <code>structured</code>
| Yes
|}

== JSON field shapes (nested specs) ==

=== Coding shape ===

The coded fields (<code>code</code>, <code>body_site</code>, <code>method</code>, <code>permitted_unit</code>) store a <code>Coding</code> object. The spec binds each to a value set via <code>ValueSetBoundCoding[<slug>]</code>, so the submitted <code>code</code> is validated against that value set on write.

<syntaxhighlight lang="text">Coding {
system: str | null
version: str | null
code: str # required
display: str | null
} # extra="forbid" — unknown keys rejected</syntaxhighlight>
{| class="wikitable"
|-
! Field
! Bound value set (slug)
! Code system
|-
| <code>code</code>
| <code>system-observation</code>
| LOINC (<code>http://loinc.org</code>)
|-
| <code>body_site</code>
| <code>system-body-site-observation</code>
| SNOMED CT (<code>http://snomed.info/sct</code>)
|-
| <code>method</code>
| <code>system-collection-method</code>
| SNOMED CT
|-
| <code>permitted_unit</code>
| <code>system-ucum-units</code>
| UCUM (<code>http://unitsofmeasure.org</code>)
|}

=== ObservationDefinitionComponentSpec ===

Element of the <code>component</code> list — one per measured value when a definition carries several.

<syntaxhighlight lang="text">ObservationDefinitionComponentSpec {
code: ValueSetBoundCoding[system-observation] # required
permitted_data_type: QuestionType # required; group/display/url rejected
permitted_unit: ValueSetBoundCoding[system-ucum-units] | null = null
qualified_ranges: list[QualifiedRangeSpec] # required
}</syntaxhighlight>
=== QualifiedRangeSpec ===

Element of <code>qualified_ranges</code> (on the definition and on each component). A qualified range is either '''numeric''' (<code>ranges</code>) or '''categorical''' (coded value sets) — never both.

<syntaxhighlight lang="text">QualifiedRangeSpec {
title: str | null = null
conditions: list[EvaluatorConditionSpec] = []
ranges: list[NumericRangeSpec] = []
default_interpretation: InterpretationSpec | null = null
normal_coded_value_set: str | null = ""
critical_coded_value_set: str | null = ""
abnormal_coded_value_set: str | null = ""
valueset_interpretation: list[ValueSetInterpretationSpec] = []
}</syntaxhighlight>
<code>validate_categorical_or_numeric</code> enforces:

* Either <code>ranges</code> (numeric) '''or''' at least one coded value set / <code>valueset_interpretation</code> (categorical) — one is required.
* Numeric <code>ranges</code> and coded value sets cannot both appear.
* Numeric <code>ranges</code> must not overlap (sorted by <code>min</code>, treating missing <code>min</code>/<code>max</code> as -∞/+∞).
* Coded value-set slugs (<code>normal_coded_value_set</code>, <code>critical_coded_value_set</code>, <code>abnormal_coded_value_set</code>, and each <code>valueset_interpretation.valuset</code>) must be unique — duplicates are rejected.

=== NumericRangeSpec ===

<syntaxhighlight lang="text">NumericRangeSpec {
interpretation: InterpretationSpec # required
min: Decimal(max_digits=20, decimal_places=6) | null = null
max: Decimal(max_digits=20, decimal_places=6) | null = null
}</syntaxhighlight>
At least one of <code>min</code>/<code>max</code> must be provided (<code>validate_range</code>).

=== InterpretationSpec ===

<syntaxhighlight lang="text">InterpretationSpec {
display: str # required
icon: str | null = ""
color: str | null = ""
highlight: bool | null = false
code: Coding | null = {}
}</syntaxhighlight>
=== ValueSetInterpretationSpec ===

<syntaxhighlight lang="text">ValueSetInterpretationSpec {
interpretation: InterpretationSpec # required
valuset: str # value-set slug (note: spelling "valuset")
}</syntaxhighlight>
=== EvaluatorConditionSpec ===

Element of <code>QualifiedRangeSpec.conditions</code>. Validated against <code>EvaluatorMetricsRegistry</code>: an unknown <code>metric</code> raises, and the registered evaluator validates <code>operation</code>/<code>value</code>.

<syntaxhighlight lang="text">EvaluatorConditionSpec {
metric: str # must resolve in EvaluatorMetricsRegistry
operation: str
value: dict | str
}</syntaxhighlight>
== Resource specs (API schema) ==

All specs subclass <code>BaseObservationDefinitionSpec</code> (itself a subclass of <code>EMRResource</code>, with <code>__model__ = ObservationDefinition</code> and <code>__exclude__ = ["facility"]</code>). <code>EMRResource</code> provides <code>serialize</code>/<code>de_serialize</code> plus the <code>perform_extra_serialization</code> / <code>perform_extra_deserialization</code> hooks.

{| class="wikitable"
|-
! Spec class
! Role
! Notable fields / behaviour
|-
| <code>BaseObservationDefinitionSpec</code>
| Shared base
| <code>id</code>, <code>title</code>, <code>status</code>, <code>description</code>, <code>category</code>, <code>code</code>, <code>permitted_data_type</code>, <code>component</code>, <code>body_site</code>, <code>method</code>, <code>permitted_unit</code>, <code>derived_from_uri</code>, <code>qualified_ranges</code>. Runs <code>validate_data_type</code> and <code>validate_qualified_ranges_consistency</code>
|-
| <code>ObservationDefinitionCreateSpec</code>
| Write · create
| Adds <code>facility: UUID4 | null</code> and <code>slug_value: SlugType</code>. Validates the facility exists; <code>perform_extra_deserialization</code> resolves the facility and sets <code>obj.slug = slug_value</code>
|-
| <code>ObservationDefinitionUpdateSpec</code>
| Write · update
| Adds <code>slug_value: SlugType</code>; <code>perform_extra_deserialization</code> sets <code>obj.slug = slug_value</code>. The facility is not re-bound on update
|-
| <code>ObservationDefinitionReadSpec</code>
| Read · list & detail
| Adds <code>version: int | null</code>, <code>facility: dict | null</code>, <code>slug_config: dict</code>, <code>slug: str</code>. <code>perform_extra_serialization</code> sets <code>id = external_id</code>, serializes <code>facility</code> via <code>FacilityBareMinimumSpec</code>, and sets <code>slug_config = parse_slug(slug)</code>
|}

Notes:

* '''Value-set bindings''' — <code>code</code>, <code>body_site</code>, <code>method</code>, <code>permitted_unit</code> (and component equivalents) are <code>ValueSetBoundCoding[...]</code>; the submitted coding is validated against the bound value set (<code>system-observation</code>, <code>system-body-site-observation</code>, <code>system-collection-method</code>, <code>system-ucum-units</code>).
* '''Data-type guard''' — <code>permitted_data_type</code> (definition and component) rejects <code>group</code>, <code>display</code>, <code>url</code>.
* '''Range consistency''' — <code>validate_qualified_ranges_consistency</code> requires every <code>qualified_ranges</code> entry on a definition to be the same kind: all numeric <code>ranges</code> or all coded value sets. Mixing raises.
* '''<code>slug_value</code>''' — <code>SlugType</code>: 5–50 chars, URL-safe (<code>[a-zA-Z0-9][a-zA-Z0-9_-]*[a-zA-Z0-9]</code>), starting and ending alphanumeric. Stored namespaced as <code>obj.slug</code> (see below).
* '''No metadata store''' — <code>__store_metadata__</code> is <code>False</code>, so spec fields map directly to model columns rather than into <code>meta</code>.

== Methods & save behaviour ==

<code>ObservationDefinition</code> overrides nothing of its own. Slug handling comes from <code>SlugBaseModel</code>, and the create/update side effects live in the API specs.

=== Slug behaviour ===

<code>SlugBaseModel</code> sets <code>FACILITY_SCOPED = True</code>, so the stored <code>slug</code> is namespaced:

<syntaxhighlight lang="text">facility-scoped: f-<facility.external_id>-<slug_value>
instance-scoped: i-<slug_value></syntaxhighlight>
* <code>calculate_slug()</code> returns the <code>f-…</code> form when <code>facility</code> is set, otherwise the <code>i-…</code> form.
* <code>parse_slug(slug)</code> validates the prefix and returns a dict: <code>{"facility": <uuid>, "slug_value": <bare slug>}</code> for <code>f-</code> slugs, or <code>{"slug_value": <bare slug>}</code> for <code>i-</code> slugs. <code>ObservationDefinitionReadSpec</code> exposes this as <code>slug_config</code>.

The create/update specs receive the bare <code>slug_value</code> and store it on <code>obj.slug</code>; the model's slug helpers apply the namespacing.

== API integration notes ==

* The facility binding is write-once: the create spec resolves the <code>facility</code> UUID to an FK; the update spec only re-sets <code>slug_value</code> and never re-binds the facility.
* Retire definitions via <code>status</code> (<code>retired</code>) instead of deleting. The inherited <code>deleted</code> flag gives you ORM-level soft-delete if you need it.
* <code>permitted_unit</code> codings follow UCUM, but Care never converts between units at display time — store data in the unit you intend to read.
* <code>convert_od_to_observation</code> (<code>observation.py</code>) builds an [[References/Observation|<code>Observation</code>]] from a definition for a given encounter, carrying over <code>category</code> and <code>code</code> and defaulting <code>status</code> to <code>final</code>.

{{Related}}

References/Observation Definition - Revision history

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

Admin: OHC identity seed