Observations

An Observation records a measurement: a vital sign, a lab result, a patient-entered value. Palamond keeps observations consistent with a few conventions: category and code come from the shared codes module, values are stored in standard (metric) units, some measurements group into panels, and reference ranges are computed for display rather than stored on every observation.

Shape

Measurements are recorded by completing a task

Your app never creates an Observation. A patient reports a reading by completing their measurement task with the values inline; the platform validates each value against its definition and writes the observations with the right LOINC coding, category, units, and encounter link. That is exactly why the record always matches the clinician's chart.

await palamond.tasks.complete(taskId, {
  measurements: [
    { loinc: '8480-6', value: 118, unit: 'mmHg', code: 'mm[Hg]' }, // systolic
    { loinc: '8462-4', value: 76, unit: 'mmHg', code: 'mm[Hg]' },  // diastolic
  ],
});

The full flow, from finding the task to reading the stored observations back, is in Capture a Vital.

Category and code come from shared codes

Do not hardcode coding systems when querying or rendering. The category coding that marks a measurement as a vital sign, and the token helper for LOINC codes, live in the shared codes module. Import them.

import { VITAL_SIGNS_CATEGORY, loinc, searchToken } from '@palamond/sdk/codes';

// All vital signs, newest first.
const vitals = await palamond.searchResources('Observation', {
  category: searchToken(VITAL_SIGNS_CATEGORY),
  _sort: '-date',
});

Standard units, metric storage

Observations are stored in standard units, and Palamond standardizes on metric storage: kilograms, centimeters, degrees Celsius, and so on. This keeps values comparable across patients and regions no matter what a UI displays.

Coupled panels

Some measurements belong together and are captured as a panel. Blood pressure is the canonical example: systolic and diastolic are captured together, written as two member observations, and grouped by a panel observation that references them via hasMember. Rendering the panel keeps the readings coupled.

import { loinc } from '@palamond/sdk/codes';

// The grouping observation carries the panel LOINC code (85354-9)
// and lists its members in hasMember.
const [panel] = await palamond.searchResources('Observation', {
  code: loinc('85354-9'),
  _sort: '-date',
  _count: 1,
});
const members = panel?.hasMember ?? [];

When you capture a panel, submit one entry per member on the task-completion call and the platform assembles the grouping observation. The members a panel should collect are declared by its capture definition, so you submit the measured values and the grouping is handled for you.

Reference ranges are computed for display

Palamond does not stamp a reference range onto every observation. Ranges are computed on the fly for display, from shared datasets keyed by the measurement and the patient's region (US, UK, EU) and demographics. This means a chart can show a normal-range band without every historical observation carrying its own range, and the band stays correct if guidelines are refined.

An observation may still carry an interpretation (low, normal, high) when it was evaluated against a definition at capture time. Read interpretation for a quick flag; compute the display band from the shared range data for the axis on a chart.

Querying a patient's observations

Searches are scoped to the signed-in patient automatically.

const vitals = await palamond.searchResources('Observation', {
  category: 'vital-signs',
  _sort: '-date',
});

Filter by code for a specific measurement, or by category to group a chart. Use date sorting to build a trend.