Skip to main content
Version: 3.1

Observation Definition

An observation definition is the master-data blueprint for a measurement — it describes how a particular observation, such as blood pressure or blood glucose, should be captured and interpreted. It is the reusable rulebook that keeps the same observation consistent every time it is recorded, no matter which form or facility collects it.

What it represents​

In Care's FHIR-aligned model, an observation definition maps to the ObservationDefinition resource. It captures:

  • What is measured — the observation's clinical code (LOINC) and its category, such as vital signs, laboratory, or survey
  • How it is measured — the permitted data type (number, text, choice, date, and so on), the unit of measurement, the collection method, and the body site
  • How to read the result — reference ranges and interpretations that flag a value as normal, abnormal, or critical, optionally varying by patient condition
  • Multiple parts of one reading — components, so a single definition like blood pressure can hold both systolic and diastolic values

The key distinction is that a definition is a template, not a recorded result. It says "a temperature is a number in degrees Celsius that reads normal between these bounds" — the actual reading taken from a patient is an Observation. Because the rules live in one place, the same observation is captured and interpreted identically everywhere it appears. One observation code can have several definitions, and each definition lives either at the instance level (shared across the deployment) or scoped to a single facility.

How it connects​

Observation definitions are reference data that other primitives draw on rather than something attached directly to a patient:

  • Questionnaires point at observation definitions so that the questions clinicians fill in collect data in a consistent, coded shape. The definition is referenced, not copied into the form.
  • Observations are produced from a definition for a specific encounter — Care can turn a definition into a blank observation, carrying over its code and category, ready to hold an actual value.
  • Value sets back every coded field (code, unit, body site, method). The submitted code is checked against the bound value set, which is what keeps the data translatable to FHIR.

Because they are shared master data, a small library of well-defined observations is reused across many forms and facilities instead of each form inventing its own fields.

Scope​

Where a definition applies depends on whether it is tied to a facility:

ScopeMeaning
Instance-wideNot bound to any facility; available across the whole deployment
Facility-scopedBound to one facility; only that facility uses it

The scope is set once when the definition is created. This lets a deployment ship a standard catalogue of observations while still allowing an individual facility to define its own.

Lifecycle​

draft → active → retired
  • draft — the definition is being authored and is not yet ready for use
  • active — the definition is in use and can be referenced by questionnaires and observations
  • retired — the definition is withdrawn from use but kept for history

Observation definitions are never destroyed. When one is no longer wanted it is moved to retired rather than deleted, so existing records that relied on it stay coherent. A separate unknown status exists for definitions whose state cannot be determined.

Permissions​

Access to observation definitions is governed by facility-scoped role permissions.

PermissionDescriptionSystem Roles
can_write_observation_definitionCreate and update observation definitions for a facilityFacility Admin, Admin
can_read_observation_definitionView observation definitions available to a facilityFacility Admin, Administrator, Admin, Staff, Doctor, Nurse, Volunteer, Pharmacist

Roles are granted through a user's organization, facility, or patient memberships, and permissions cascade down the organization tree — so authoring is restricted to administrators while most clinical roles can read the definitions they need to collect data.