Realtime · Schema

Realtime Message Envelope

A canonical envelope describing a single message flowing across a realtime channel — the framing that providers wrap around user payloads. This envelope generalizes the message shapes used by Ably, Pusher, PubNub, Socket.IO, MQTT 5 (with user properties), graphql-ws, and CloudEvents-over-WebSocket.

RealtimeWebSocketWebRTCServer-Sent EventsMQTTPush NotificationsPub SubPresenceSignalingTopic

Properties

Name	Type	Description
id	string	A unique identifier for the message — typically a ULID, UUID, or provider-assigned message ID. Used for deduplication and resume-from-checkpoint.
channel	string	Channel name to which the message was published.
event	string	Application-defined event name or message type (e.g., 'message.created', 'order.updated', 'user.joined'). Maps to Ably 'name', Pusher 'event', Socket.IO event names, and CloudEvents 'type'.
data	object	The application payload. Often JSON, but may be a base64-encoded binary buffer, plain text, or a primitive value.
encoding	string	Encoding of the data field when not JSON.
contentType	string	IANA media type of the payload (e.g., 'application/json', 'application/vnd.example.event+json').
publishedAt	string	Time the message was accepted by the realtime provider.
receivedAt	string	Time the message was delivered to the subscribing client (set client-side).
clientId	string	Identifier of the publishing client connection or user. Maps to Ably clientId, MQTT ClientID, Socket.IO socket.id.
connectionId	string	Provider-assigned identifier for the transport connection that originated the message.
qualityOfService	string	Delivery guarantee applied to this message.
sequence	integer	Per-channel monotonically increasing sequence number for ordering and gap detection.
correlationId	string	Correlation identifier linking this message to a request, trace, or higher-level workflow.
replyTo	string	Channel name on which the publisher expects a response (request/response pattern over pub/sub).
expiresAt	string	Time at which the message is considered stale and may be discarded by the broker or consumer.
headers	object	Provider-level metadata or user properties (modeled on MQTT 5 User Properties, AMQP application properties, and HTTP headers).
trace	object	Distributed tracing context propagated with the message.

View JSON Schema on GitHub

JSON Schema

{
  "$id": "realtime-message-envelope.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Realtime Message Envelope",
  "description": "A canonical envelope describing a single message flowing across a realtime channel — the framing that providers wrap around user payloads. This envelope generalizes the message shapes used by Ably, Pusher, PubNub, Socket.IO, MQTT 5 (with user properties), graphql-ws, and CloudEvents-over-WebSocket.",
  "type": "object",
  "required": [
    "id",
    "channel",
    "data"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier for the message — typically a ULID, UUID, or provider-assigned message ID. Used for deduplication and resume-from-checkpoint."
    },
    "channel": {
      "type": "string",
      "description": "Channel name to which the message was published."
    },
    "event": {
      "type": "string",
      "description": "Application-defined event name or message type (e.g., 'message.created', 'order.updated', 'user.joined'). Maps to Ably 'name', Pusher 'event', Socket.IO event names, and CloudEvents 'type'."
    },
    "data": {
      "description": "The application payload. Often JSON, but may be a base64-encoded binary buffer, plain text, or a primitive value.",
      "oneOf": [
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "null"
        }
      ]
    },
    "encoding": {
      "type": "string",
      "description": "Encoding of the data field when not JSON.",
      "enum": [
        "json",
        "utf-8",
        "base64",
        "protobuf",
        "msgpack",
        "cbor",
        "binary"
      ]
    },
    "contentType": {
      "type": "string",
      "description": "IANA media type of the payload (e.g., 'application/json', 'application/vnd.example.event+json')."
    },
    "publishedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time the message was accepted by the realtime provider."
    },
    "receivedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time the message was delivered to the subscribing client (set client-side)."
    },
    "clientId": {
      "type": "string",
      "description": "Identifier of the publishing client connection or user. Maps to Ably clientId, MQTT ClientID, Socket.IO socket.id."
    },
    "connectionId": {
      "type": "string",
      "description": "Provider-assigned identifier for the transport connection that originated the message."
    },
    "qualityOfService": {
      "type": "string",
      "description": "Delivery guarantee applied to this message.",
      "enum": [
        "at-most-once",
        "at-least-once",
        "exactly-once"
      ]
    },
    "sequence": {
      "type": "integer",
      "description": "Per-channel monotonically increasing sequence number for ordering and gap detection.",
      "minimum": 0
    },
    "correlationId": {
      "type": "string",
      "description": "Correlation identifier linking this message to a request, trace, or higher-level workflow."
    },
    "replyTo": {
      "type": "string",
      "description": "Channel name on which the publisher expects a response (request/response pattern over pub/sub)."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time at which the message is considered stale and may be discarded by the broker or consumer."
    },
    "headers": {
      "type": "object",
      "description": "Provider-level metadata or user properties (modeled on MQTT 5 User Properties, AMQP application properties, and HTTP headers).",
      "additionalProperties": {
        "type": "string"
      }
    },
    "trace": {
      "type": "object",
      "description": "Distributed tracing context propagated with the message.",
      "properties": {
        "traceparent": {
          "type": "string",
          "description": "W3C traceparent header value."
        },
        "tracestate": {
          "type": "string",
          "description": "W3C tracestate header value."
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}