Clinical care

Observation Definition

An ObservationDefinition is master data describing how a particular observation is captured — its code, permitted data type, unit, method, body site, and reference ranges. You create one when you need a measurement collected consistently across…

3.1 · versioned documentation · 8 min read

An ObservationDefinition 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 FHIR ObservationDefinition resource.

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

Source:

• Model: care/emr/models/observation_definition.py
• Resource spec: care/emr/resources/observation_definition/spec.py
• Helper: care/emr/resources/observation_definition/observation.py

Models

ObservationDefinition extends SlugBaseModel, which adds facility-scoped slug helpers on top of EMRBaseModel. From EMRBaseModel it inherits external_id, created_date/modified_date, soft-delete via deleted, created_by/updated_by, and the history/meta JSON fields.

ObservationDefinition fields

Identity & scope

Coding & measurement

Components & ranges

Enum values

Status values

ObservationStatusChoices — bound to the status field.

Category values

ObservationCategoryChoices — bound to the category field.

Permitted data type values

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

JSON field shapes (nested specs)

Coding shape

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

Coding {
  system:  str | null
  version: str | null
  code:    str            # required
  display: str | null
}                          # extra="forbid" — unknown keys rejected

ObservationDefinitionComponentSpec

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

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
}

QualifiedRangeSpec

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

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] = []
}

validate_categorical_or_numeric enforces:

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

NumericRangeSpec

NumericRangeSpec {
  interpretation: InterpretationSpec          # required
  min: Decimal(max_digits=20, decimal_places=6) | null = null
  max: Decimal(max_digits=20, decimal_places=6) | null = null
}

At least one of min/max must be provided (validate_range).

InterpretationSpec

InterpretationSpec {
  display:   str             # required
  icon:      str | null = ""
  color:     str | null = ""
  highlight: bool | null = false
  code:      Coding | null = {}
}

ValueSetInterpretationSpec

ValueSetInterpretationSpec {
  interpretation: InterpretationSpec   # required
  valuset:        str                  # value-set slug (note: spelling "valuset")
}

EvaluatorConditionSpec

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

EvaluatorConditionSpec {
  metric:    str          # must resolve in EvaluatorMetricsRegistry
  operation: str
  value:     dict | str
}

Resource specs (API schema)

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

Notes:

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

Methods & save behaviour

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

Slug behaviour

SlugBaseModel sets FACILITY_SCOPED = True, so the stored slug is namespaced:

facility-scoped: f-<facility.external_id>-<slug_value>
instance-scoped: i-<slug_value>

• calculate_slug() returns the f-… form when facility is set, otherwise the i-… form.
• parse_slug(slug) validates the prefix and returns a dict: {"facility": <uuid>, "slug_value": <bare slug>} for f- slugs, or {"slug_value": <bare slug>} for i- slugs. ObservationDefinitionReadSpec exposes this as slug_config.

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

API integration notes

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

Related

• Reference: Observation
• Reference: Service Request
• Reference: Questionnaire
• Reference: Value Set
• Reference: Base model
• Source: observation_definition.py (model)
• Source: observation_definition/spec.py (resource spec)
• Source: observation/valueset.py (bound value sets)

Source evidence

References are pinned to the private MANSOQ source repository. Repository access is required to open these links.

• repositories/platform/mansoq-documentation/versioned_docs/version-3.1/references/definitions/observation-definition.mdx:1 · f6e9f05f