Schema 3.5.0

Changed — payloads are records#

ClientEvent.payload, ClientIssue.payload, ClientMetaData.payload and ExtensionStat.payload changed from an optional string to an optional map of primitives — Record<string, boolean | string | number> in the generated TypeScript (Avro: ["null", {"type": "map", "values": ["boolean", "string", "double"]}], keeping the null-first optional convention).

Producers no longer JSON.stringify every payload before buffering it, and consumers read payload fields directly instead of parsing a nested JSON document.

// before
{ "type": "MEDIA_TRACK_MUTED", "payload": "{\"trackId\":\"t-1\",\"kind\":\"audio\"}" }

// 3.5.0
{ "type": "MEDIA_TRACK_MUTED", "payload": { "trackId": "t-1", "kind": "audio" } }

Why — measured, not argued#

Measured on Node 22 with realistic samples carrying 35–40 payloads:

Each payload was previously walked twice: once by its own JSON.stringify at buffering time (30–40 calls per sample, now zero, along with their intermediate-string garbage) and once more character-by-character for escaping. Payload fields also become directly queryable without a second parse.

Codec impact#

• Protobuf: the payload still travels as a JSON string, because proto3 cannot express a union-valued map — the same convention attachments uses. The protobuf codec converts it through its JSON-fields mechanism, keyed on the field name, so all four payload fields are covered and protobuf field numbering is unchanged.
• JSON: no change needed. Events, issues, meta items and extension stats are value lists written whole, and object values were already handled generically.

The TypeScript generator learned to render union-valued Avro maps for this.

Upgrading#

// before
const payload = JSON.parse(event.payload ?? '{}');

// 3.5.0
const payload = event.payload ?? {};

A reader that must accept both generations does what the observer does: pass an object through untouched, parse a string.

← Back to version history · 3.4.0 →