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
- A diagnosis is a Condition. A grade of that diagnosis is a ClinicalState.
- The questionnaire answers stay on the Assessment. The score, once finalized, is an Observation.
- This resource does not store the form layout. That is a Definition.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| code | 1..1 | code | B | Local or system code, for example phq9_score or loinc:8480-6. |
| display | 0..1 | string | — | Human label. |
| system | 0..1 | code | — | Code system: loinc, snomed, or local. |
| category | 1..1 | code | B | vital, lab, score, symptom, finding, social, lifestyle, note, or other. |
| value | 0..1 | Quantity | string | boolean | object | — | The value. Units go in unit. |
| unit | 0..1 | string | — | Unit of measure. |
| effective_at | 1..1 | dateTime | — | When the fact was true, not when it was typed. |
| perceived_by | 1..1 | code | B | patient, care_team, or device. |
| source_kind | 0..1 | code | — | Resource that produced it: note_page, assessment, journal_entry. |
| source_id | 0..1 | id | — | That resource's id. |
| encounter_id | 0..1 | id | — | Encounter, when the fact was captured in one. |
| tags | 0..* | code | — | Free tags for profiles and search. |
State machine
preliminary— Not yet confirmed.final/ initial — The usual state on create.amended— Replaced by a correction. The previous row stays.entered_in_error— Withdrawn. Frozen.
preliminary → final, entered_in_error. final → amended, entered_in_error. amended → amended, entered_in_error.
Frozen: entered_in_error.
Terminology bindings
| Element | Strength | Values |
|---|---|---|
| category | required | vital | lab | score | symptom | finding | social | lifestyle | note | other |
| perceived_by | required | patient | care_team | device |
Invariants
ccs-obs-1— Clinical observations are not deleted. Withdraw with entered_in_error.ccs-obs-2— A finalized note block or assessment writes the observation. The form does not.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/observations | List observation. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/observations | Create 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}/transition | Move 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" }