Clinical Intelligence StandardsVersion 0.2

Functional standard / How they are / PatientInstance

Observation

One coded fact: a vital, a lab, a score, a symptom, a finding.

Kind
observation
Collection
/v1/observations
Initial state
final
Classification
Operational

Scope and usage

The atomic clinical fact. Note pages, assessments, journals, devices, and conversations write observations. They do not invent a second fact type.

Boundaries and relationships

Resource content

Elements this resource adds. It also carries the Instance, including patient_id.

NameCard.TypeFlagsDescription
code1..1codeBLocal or system code, for example phq9_score or loinc:8480-6.
display0..1string—Human label.
system0..1code—Code system: loinc, snomed, or local.
category1..1codeBvital, lab, score, symptom, finding, social, lifestyle, note, or other.
value0..1Quantity | string | boolean | object—The value. Units go in unit.
unit0..1string—Unit of measure.
effective_at1..1dateTime—When the fact was true, not when it was typed.
perceived_by1..1codeBpatient, care_team, or device.
source_kind0..1code—Resource that produced it: note_page, assessment, journal_entry.
source_id0..1id—That resource's id.
encounter_id0..1id—Encounter, when the fact was captured in one.
tags0..*code—Free tags for profiles and search.

State machine

preliminary → final, entered_in_error. final → amended, entered_in_error. amended → amended, entered_in_error.

Frozen: entered_in_error.

Terminology bindings

ElementStrengthValues
categoryrequiredvital | lab | score | symptom | finding | social | lifestyle | note | other
perceived_byrequiredpatient | care_team | device

Invariants

Operations

MethodPathMeaning
GET/v1/observationsList observation. Filter by patient_id, status, and where the model has them, encounter_id or definition_key.
POST/v1/observationsCreate a observation. Body is the resource minus harness-owned elements.
GET/v1/observations/{id}Read one observation.
PATCH/v1/observations/{id}Update elements that are not immutable, frozen, or harness-owned.
POST/v1/observations/{id}/transitionMove status. Body is { to, reason }. A gated move returns 202 and an Approval.

Example

{ "patient_id": "pat_…", "code": "loinc:8480-6", "category": "vital", "value": 128, "unit": "mmHg", "perceived_by": "care_team" }