observation

A named trend series for a patient — e.g. a repeated measurement taken over time — sourced from the provider's clinical record. Unlike condition or procedure, an observation record is an aggregate: as new measurements are taken, the same record is updated in place with a growing set of points rather than a new record being created per measurement.

Fields

Field	Type	Required	Description
identifiers	Identifier[]	yes (≥1)	Business identifiers for this observation series.
patientRef	SourceRef	yes	The patient this trend series belongs to.
name	string	yes	The name of the measurement, e.g. "Grip strength (right hand)".
summary	string	no	Free-text summary of the trend.
latestResult	string	no	Free-text rendering of the most recent point.
discipline	string	no	The clinical discipline recording this series, e.g. physiotherapy.
points	ObservationPoint[] (below)	no (defaults [])	The recorded measurements, oldest to newest.

Observation point

Field	Type	Required	Description
recordedAt	string	yes	Source-provided date or label for this point — not guaranteed to be ISO-8601, unlike the normalized timestamps used elsewhere.
value	string | number	yes	The recorded value.
unit	string	no	Unit for value, e.g. kg.

Example payload

{
  "identifiers": [{ "system": "urn:michels:observation", "value": "OBS-4001" }],
  "patientRef": {
    "sourceSystem": "michels",
    "resourceType": "patient",
    "sourceId": "pat-1"
  },
  "name": "Grip strength (right hand)",
  "summary": "Improving over the last three sessions",
  "latestResult": "24 kg",
  "discipline": "physiotherapy",
  "points": [
    { "recordedAt": "2026-06-30", "value": 19, "unit": "kg" },
    { "recordedAt": "2026-07-07", "value": 22, "unit": "kg" },
    { "recordedAt": "2026-07-14", "value": 24, "unit": "kg" }
  ]
}

As a change-feed event

This record has been updated in place since it was first created — the event below is an update at version: 2, carrying the full current payload (including all three points), not just the point that was added:

{
  "sequence": 103,
  "resourceType": "observation",
  "canonicalId": "8e2b5c9a-1d4f-4a7c-8b2e-5d9a1c4f7b2e",
  "operation": "update",
  "version": 2,
  "occurredAt": "2026-07-14T09:00:00.000Z",
  "orgSlug": "default",
  "record": {
    "identifiers": [{ "system": "urn:michels:observation", "value": "OBS-4001" }],
    "patientRef": {
      "sourceSystem": "michels",
      "resourceType": "patient",
      "sourceId": "pat-1"
    },
    "name": "Grip strength (right hand)",
    "summary": "Improving over the last three sessions",
    "latestResult": "24 kg",
    "discipline": "physiotherapy",
    "points": [
      { "recordedAt": "2026-06-30", "value": 19, "unit": "kg" },
      { "recordedAt": "2026-07-07", "value": 22, "unit": "kg" },
      { "recordedAt": "2026-07-14", "value": 24, "unit": "kg" }
    ]
  }
}

From the Records API

curl -H "Authorization: Bearer $ROSETTA_SYNC_TOKEN" \
  "https://sync.example.com/api/v1/records/observation/8e2b5c9a-1d4f-4a7c-8b2e-5d9a1c4f7b2e"

{
  "id": "8e2b5c9a-1d4f-4a7c-8b2e-5d9a1c4f7b2e",
  "resourceType": "observation",
  "version": 2,
  "payload": {
    "identifiers": [{ "system": "urn:michels:observation", "value": "OBS-4001" }],
    "patientRef": {
      "sourceSystem": "michels",
      "resourceType": "patient",
      "sourceId": "pat-1"
    },
    "name": "Grip strength (right hand)",
    "summary": "Improving over the last three sessions",
    "latestResult": "24 kg",
    "discipline": "physiotherapy",
    "points": [
      { "recordedAt": "2026-06-30", "value": 19, "unit": "kg" },
      { "recordedAt": "2026-07-07", "value": 22, "unit": "kg" },
      { "recordedAt": "2026-07-14", "value": 24, "unit": "kg" }
    ]
  },
  "updatedAt": "2026-07-14T09:00:00.000Z",
  "orgSlug": "default",
  "identifiers": [{ "system": "urn:michels:observation", "value": "OBS-4001" }]
}

Consumption notes

• This is an aggregate updated in place, not an immutable clinical fact — a new change event carries the whole payload again (a full-record event), not just the new point. Always overwrite your stored copy of the record rather than merging points arrays element-wise, and dedupe applied events on (canonicalId, version).
• points[].recordedAt is a free-form source label, not a normalized timestamp — do not assume it parses as ISO-8601. Sort and parse it defensively; some source systems may report a label rather than a date.
• points[].value is a union type (string or number) — branch on its JSON type before using it, rather than assuming one or the other.
• patientRef is a source reference; correlate it to the canonical patient whose identifiers contain the matching business identifier.