Common Data Item Fields

Every data item in the envelope’s data[] array carries these common fields, regardless of event type.

Structure

{
  "event_type": "activity",
  "data_version": "1.1",
  "source_id": "a1b2c3d4e5f6...",
  "provider_ref": "12345",
  "device_id": "dev-001",
  "payload_ts": 1742558400000,
  "revision": 1,
  "capture_mode": null
}

Event-type pages document additional fields after these common keys.

Field Reference

Field	Type	Description
event_type	string	Data type discriminator. Always matches the envelope’s event_type. Included on each item for self-contained parsing.
data_version	string	Schema version for this specific data type. Evolves independently of the envelope schema_version. Normalized items currently use 1.1 (common capture_mode on every type).
source_id	string	Nexus-generated deterministic ID. Same data point re-fetched = same source_id. See Source ID & Revisions.
provider_ref	string	Raw provider ID for debugging and provider API lookups.
device_id	string | null	References a device_id in the envelope’s devices[] array. null when device attribution is unavailable.
payload_ts	number (epoch ms)	Authoritative timestamp of this data point.
revision	number	Starts at 1 for first delivery. Increments when a provider retroactively corrects data.
capture_mode	string | null	manual, automatic, or null. Present on every data item (normative: repo docs/EVENT_FORMAT_SPEC.md, Common Data Item Fields). Activities: Fitbit maps activity log logType; mock-provider may set optional capture_mode on the raw payload. Other event types use null until a provider exposes a mappable signal.

Nullability Rule

Fields not available from a provider are set to null, never omitted. This means consumers can safely type their responses against the full schema without checking for field existence.

{
  "event_type": "body_measurement",
  "data_version": "1.1",
  "source_id": "c3d4e5f6...",
  "provider_ref": "w-abc123",
  "device_id": null,
  "payload_ts": 1742558400000,
  "revision": 1,
  "capture_mode": null,
  "weight_kg": 75.5,
  "height_cm": null,
  "bmi": 23.8,
  "body_fat_pct": null,
  "lean_mass_kg": null
}

Versioning

The data_version field tracks per-type schema evolution independently of the envelope’s schema_version:

• Envelope schema_version: Changes when the envelope structure itself changes (new top-level fields, altered routing semantics).
• Data item data_version: Changes when a specific event type gains or modifies fields. Version 1.1 introduced the common capture_mode field on all data items.

This two-level scheme lets consumers handle envelope changes and data changes on separate upgrade paths.