Data shape

WearMetrics is the single shape every adapter writes into. Downstream layers (synheart-session, synheart-core, the runtime ingest queue) read this shape; they do not consume vendor-specific JSON.

`WearMetrics`

class WearMetrics {
  final DateTime timestamp;
  final String deviceId;
  final String source;
  final Map<String, num?> metrics;
  final Map<String, Object?> meta;
  final List<double>? rrIntervalsMs;
}

This is the Flutter class. Kotlin and Swift carry the same fields with a few differences: RR intervals are rrIntervals, meta holds strings only, and battery is a metric (BATTERY / .battery) instead of meta.battery. JSON shape (canonical, Flutter toJson()):

{
  "timestamp": "2025-10-20T18:30:00Z",
  "device_id": "applewatch_1234",
  "source": "apple_healthkit",
  "metrics": {
    "hr": 72,
    "hrv_rmssd": 45,
    "hrv_sdnn": 62,
    "steps": 1045,
    "calories": 120.4,
    "distance": 2.5,
    "stress": 23
  },
  "meta": {
    "battery": 0.82,
    "synced": true
  },
  "rr_ms": [800, 850, 820]
}

Top-level fields

Field	Type	Notes
`timestamp`	ISO-8601 UTC string	Time the measurement applies to (sample time, not emit time). Always UTC.
`device_id`	string	Stable identifier for this physical device. Format is vendor-shaped (e.g. `"applewatch_1234"`, `"whoop_<uuid>"`; for a BLE HRM, the MAC address on Android and the CoreBluetooth peripheral UUID on iOS).
`source`	string	Lowercase snake_case adapter id. Stable across versions of the same adapter.
`metrics`	object	Keyed by metric short-name (see below). Values may be `null` when the adapter knows the metric is not available; missing keys mean “not produced by this sample”.
`meta`	object	Free-form per-sample metadata. Stable keys are documented below; adapters may add vendor-specific keys.
`rr_ms`	array of doubles \| absent	Inter-beat intervals in milliseconds when the source provides them. Absent when not available.

`metrics` keys

Maps from the MetricType enum:

Key	Type	Unit	Source
`hr`	number	bpm	HR sample.
`hrv_rmssd`	number	ms	HRV (RMSSD) over the adapter’s window.
`hrv_sdnn`	number	ms	HRV (SDNN) over the adapter’s window.
`steps`	number	count	Period total (since the previous sample, or per-day depending on adapter).
`calories`	number	kcal	Active energy.
`distance`	number	km (Flutter), meters (Kotlin)	Total distance over the period. Swift doesn’t read distance from HealthKit.
`stress`	number	unitless	Vendor-specific score (e.g. Garmin `0–100`); adapters do not normalise this across vendors.

HealthKit and Health Connect each report a single HRV figure: SDNN and RMSSD respectively. They are different statistics, so each is stored only under its own key (hrv_sdnn from HealthKit, hrv_rmssd from Health Connect) and the other key is absent. Flutter releases before 0.7.0 copied the one value into both keys. Adapters MAY emit additional vendor-specific metric keys but downstream consumers MUST tolerate unknown keys. Stable keys above are the normalised contract.

`meta` keys (stable)

Key	Type	Notes
`battery`	number 0–1	Device battery level.
`synced`	bool	`true` when the sample came from a vendor sync or backfill (WHOOP and Garmin cloud set it). Read back as `WearMetrics.isSynced`.

Adapter-specific meta on Flutter: Garmin cloud adds garmin_data (the vendor record), body_battery, vo2_max, fitness_age and source_type; when Garmin reports no stress value, stress falls back to 100 - body_battery. WHOOP cloud adds recovery_score, strain_score, sleep_score, whoop_data and source_type.

`rr_ms` semantics

When present:

Each value is one inter-beat interval in milliseconds.
Order is the order observed by the device (chronological).
The list is per sample, not cumulative — multiple samples at the same timestamp can share an rr_ms payload via the meta field.
Range gates apply downstream: the runtime’s RR push rejects values outside [200, 6000].

Adapter source IDs

The top-level source field carries the adapter id — typically the bare vendor/source name. More specific flavor information (cloud vs BLE, etc.) lives in meta.source_type.

`source` value	Adapter	`meta.source_type` flavor
`"apple_healthkit"`	Apple HealthKit	—
`"health_connect"`	Android Health Connect	— (Flutter releases before 0.7.0 labelled it `"apple_healthkit"`)
`"ble_hrm"`	BLE Heart Rate Profile	—
`"whoop"`	WHOOP	`"whoop_cloud"` for OAuth + webhooks; WHOOP via BLE Broadcast HR uses `source = "ble_hrm"`
`"garmin"`	Garmin via Connect API	`"garmin_cloud"`
`"garmin_sdk"`	Garmin Health SDK (RTS, license-gated)	—
`"fitbit"`	Fitbit	—
`"oura"`	Oura	— (cloud OAuth provider)

Consumers MUST tolerate unknown source and meta.source_type values. When new adapters land, they take new stable strings. Existing strings do not change meaning.

Compatibility rules

The shape is unversioned. Compatibility rules:

Producers MAY add new metric keys, new meta keys, and new source values.
Producers MUST NOT remove or rename existing keys.
Consumers MUST tolerate unknown metric keys and unknown source values.
A future change to the top-level shape would be a breaking change; the SDK would expose both producers in parallel during migration.

Vendor → schema mapping (informal)

This table is informational only. Each adapter is the authoritative source for its mapping; this is a reading aid.

Vendor field	Maps to	Notes
HealthKit `HKQuantityTypeIdentifierHeartRate`	`metrics.hr`	Average per query window.
HealthKit RR samples	`rr_ms`	Workout-mode only on most Apple Watch models.
Health Connect `HeartRateRecord`	`metrics.hr`	One sample per record.
WHOOP webhook `recovery_score`	`meta.recovery_score`	Not part of the canonical metric set.
Garmin Connect `restingHeartRate`	`metrics.hr`	Daily resting HR baseline.
BLE GATT 0x180D HR characteristic	`metrics.hr`	Plus optional RR field → `rr_ms`.
Apple XML `HKQuantityTypeIdentifierHeartRateVariabilitySDNN`	`metrics.hrv_sdnn`	Backfill only.

How downstream uses this

synheart-session turns wear readings into its own BiosignalSamples:

Swift: HealthKitBiosignalProvider(wear:) reads streamHR, and WearBiosignalProvider(bleHrmProvider:) bridges a BLE HRM, carrying its RR intervals as a list.
Kotlin: WearBiosignalProvider bridges a BLE HRM; HealthConnectBiosignalProvider polls Health Connect.
Flutter: the session SDK gets HR from the watch (WatchBiosignalProvider), not from synheart_wear.

synheart-core forwards the same shape into the runtime via pushHr / pushRr after consent gating.

Wear Overview — full SDK surface.
Adapters — per-vendor flow.
Errors — failure modes.

Get Started

Security

Setup

CLI

Synapse

Platform

HSI

Synheart Wear

Synheart Auth

Synheart Core

Synheart Behavior

Syni

Syni Spec

Synheart Session

RAMEN 🍜

Lab Mode

Privacy

Guides

`WearMetrics`

Top-level fields

`metrics` keys

`meta` keys (stable)

`rr_ms` semantics

Adapter source IDs

Compatibility rules

Vendor → schema mapping (informal)

How downstream uses this

WearMetrics

Top-level fields

metrics keys

meta keys (stable)

rr_ms semantics

Adapter source IDs

Compatibility rules

Vendor → schema mapping (informal)

How downstream uses this

Related

`WearMetrics`

`metrics` keys

`meta` keys (stable)

`rr_ms` semantics