Realtime · Schema

Realtime Subscription

A subscription record describing a client's interest in messages from one or more realtime channels. Captures the subscription identifier, the channel pattern, delivery preferences, and filter expressions. Generalizes MQTT subscriptions, Socket.IO room joins, graphql-ws subscription operations, and Pusher channel subscribe events.

RealtimeWebSocketWebRTCServer-Sent EventsMQTTPush NotificationsPub SubPresenceSignalingTopic

Properties

Name	Type	Description
id	string	A unique identifier for this subscription, scoped to the client connection.
channel	string	The channel name or topic filter the client subscribes to. May contain wildcards depending on the protocol (MQTT '+', '#'; AMQP '*', '#').
clientId	string	Identifier of the subscribing client or user.
connectionId	string	Provider-assigned identifier for the underlying transport connection.
protocol	string	Underlying realtime protocol carrying the subscription.
qualityOfService	string	Requested delivery guarantee for messages matched by this subscription.
filter	object	Server-side filtering applied to messages before delivery.
rewind	object	Replay/rewind configuration for catching up on missed messages on subscribe.
presence	boolean	Whether the subscription should also receive presence events for the channel.
subscribedAt	string	Time the subscription was created.
expiresAt	string	Time at which the subscription is automatically cancelled, if any.

View JSON Schema on GitHub

JSON Schema

{
  "$id": "realtime-subscription.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Realtime Subscription",
  "description": "A subscription record describing a client's interest in messages from one or more realtime channels. Captures the subscription identifier, the channel pattern, delivery preferences, and filter expressions. Generalizes MQTT subscriptions, Socket.IO room joins, graphql-ws subscription operations, and Pusher channel subscribe events.",
  "type": "object",
  "required": [
    "id",
    "channel",
    "clientId"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "A unique identifier for this subscription, scoped to the client connection."
    },
    "channel": {
      "type": "string",
      "description": "The channel name or topic filter the client subscribes to. May contain wildcards depending on the protocol (MQTT '+', '#'; AMQP '*', '#')."
    },
    "clientId": {
      "type": "string",
      "description": "Identifier of the subscribing client or user."
    },
    "connectionId": {
      "type": "string",
      "description": "Provider-assigned identifier for the underlying transport connection."
    },
    "protocol": {
      "type": "string",
      "description": "Underlying realtime protocol carrying the subscription.",
      "enum": [
        "websocket",
        "sse",
        "webrtc",
        "mqtt",
        "coap",
        "grpc",
        "graphql-ws",
        "graphql-sse",
        "webtransport",
        "http-long-poll",
        "proprietary"
      ]
    },
    "qualityOfService": {
      "type": "string",
      "description": "Requested delivery guarantee for messages matched by this subscription.",
      "enum": [
        "at-most-once",
        "at-least-once",
        "exactly-once"
      ]
    },
    "filter": {
      "type": "object",
      "description": "Server-side filtering applied to messages before delivery.",
      "properties": {
        "expression": {
          "type": "string",
          "description": "Filter expression (e.g., SQL-like, JMESPath, CEL) interpreted by the provider."
        },
        "language": {
          "type": "string",
          "description": "Language identifier for the expression.",
          "enum": [
            "sql",
            "jmespath",
            "cel",
            "jsonpath",
            "mqtt-topic",
            "custom"
          ]
        }
      },
      "additionalProperties": false
    },
    "rewind": {
      "type": "object",
      "description": "Replay/rewind configuration for catching up on missed messages on subscribe.",
      "properties": {
        "from": {
          "type": "string",
          "description": "Resume position — a message ID, sequence number, or ISO 8601 timestamp."
        },
        "limit": {
          "type": "integer",
          "description": "Maximum number of historical messages to deliver.",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "presence": {
      "type": "boolean",
      "description": "Whether the subscription should also receive presence events for the channel."
    },
    "subscribedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time the subscription was created."
    },
    "expiresAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time at which the subscription is automatically cancelled, if any."
    }
  },
  "additionalProperties": false
}