Websocket schema — API Protocol reference Defines the schema for WebSocket-based real-time communication in ObjectStack.
WebSocket Event Protocol
Defines the schema for WebSocket-based real-time communication in ObjectStack.
Supports event subscriptions, filtering, presence tracking, and collaborative editing.
Industry alignment: Firebase Realtime Database, Socket.IO, Pusher
⚠️ NOT YET SERVED — this protocol is declared but no WebSocket server is
mounted anywhere in the runtime (#2462, #3197): IRealtimeService.handleUpgrade
is deliberately unimplemented and discovery advertises websockets: false.
These schemas define the future wire contract; nothing consumes them at
runtime today.
Source: packages/spec/src/api/websocket.zod.ts
import { AckMessageSchema, CursorMessageSchema, CursorPositionSchema, DocumentStateSchema, EditMessageSchema, EditOperationSchema, EditOperationType, ErrorMessageSchema, EventMessageSchema, EventPatternSchema, EventSubscriptionSchema, PingMessageSchema, PongMessageSchema, PresenceMessageSchema, PresenceStateSchema, PresenceUpdateSchema, SimpleCursorPositionSchema, SimplePresenceStateSchema, SubscribeMessageSchema, UnsubscribeMessageSchema, UnsubscribeRequestSchema, WebSocketConfigSchema, WebSocketEventSchema, WebSocketMessageSchema, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfigSchema } from '@objectstack/spec/api' ; import type { AckMessage, CursorMessage, CursorPosition, DocumentState, EditMessage, EditOperation, EditOperationType, ErrorMessage, EventMessage, EventPattern, EventSubscription, PingMessage, PongMessage, PresenceMessage, PresenceState, PresenceUpdate, SimpleCursorPosition, SimplePresenceState, SubscribeMessage, UnsubscribeMessage, UnsubscribeRequest, WebSocketConfig, WebSocketEvent, WebSocketMessage, WebSocketMessageType, WebSocketPresenceStatus, WebSocketServerConfig } from '@objectstack/spec/api' ; // Validate data const result = AckMessageSchema. parse (data); Property Type Required Description messageId string✅ Unique message identifier type 'ack'✅ timestamp string✅ ISO 8601 datetime when message was sent ackMessageId string✅ ID of the message being acknowledged success boolean✅ Whether the operation was successful error stringoptional Error message if operation failed
Property Type Required Description messageId string✅ Unique message identifier type 'cursor'✅ timestamp string✅ ISO 8601 datetime when message was sent cursor { userId: string; sessionId: string; documentId: string; position?: object; … }✅ Cursor position
Property Type Required Description userId string✅ User identifier sessionId string✅ Session identifier documentId string✅ Document identifier being edited position { line: integer; column: integer }optional Cursor position in document selection { start: object; end: object }optional Selection range (if text is selected) color stringoptional Cursor color for visual representation userName stringoptional Display name of user lastUpdate string✅ ISO 8601 datetime of last cursor update
Property Type Required Description userId string✅ User identifier sessionId string✅ Session identifier documentId string✅ Document identifier being edited position { line: integer; column: integer }optional Cursor position in document selection { start: object; end: object }optional Selection range (if text is selected) color stringoptional Cursor color for visual representation userName stringoptional Display name of user lastUpdate string✅ ISO 8601 datetime of last cursor update
Property Type Required Description line integer✅ Line number (0-indexed) column integer✅ Column number (0-indexed)
Property Type Required Description documentId string✅ Document identifier version integer✅ Current document version content string✅ Current document content lastModified string✅ ISO 8601 datetime of last modification activeSessions string[]✅ Active editing session IDs checksum stringoptional Content checksum for integrity verification
Property Type Required Description messageId string✅ Unique message identifier type 'edit'✅ timestamp string✅ ISO 8601 datetime when message was sent operation { operationId: string; documentId: string; userId: string; sessionId: string; … }✅ Edit operation
Property Type Required Description operationId string✅ Unique operation identifier documentId string✅ Document identifier userId string✅ User who performed the edit sessionId string✅ Session identifier type Enum<'insert' | 'delete' | 'replace'>✅ Type of edit operation position { line: integer; column: integer }✅ Starting position of the operation endPosition { line: integer; column: integer }optional Ending position (for delete/replace operations) content stringoptional Content to insert/replace version integer✅ Document version before this operation timestamp string✅ ISO 8601 datetime when operation was created baseOperationId stringoptional Previous operation ID this builds upon (for OT)
Property Type Required Description operationId string✅ Unique operation identifier documentId string✅ Document identifier userId string✅ User who performed the edit sessionId string✅ Session identifier type Enum<'insert' | 'delete' | 'replace'>✅ Type of edit operation position { line: integer; column: integer }✅ Starting position of the operation endPosition { line: integer; column: integer }optional Ending position (for delete/replace operations) content stringoptional Content to insert/replace version integer✅ Document version before this operation timestamp string✅ ISO 8601 datetime when operation was created baseOperationId stringoptional Previous operation ID this builds upon (for OT)
Property Type Required Description line integer✅ Line number (0-indexed) column integer✅ Column number (0-indexed)
Property Type Required Description messageId string✅ Unique message identifier type 'error'✅ timestamp string✅ ISO 8601 datetime when message was sent code string✅ Error code message string✅ Error message details anyoptional Additional error details
Property Type Required Description messageId string✅ Unique message identifier type 'event'✅ timestamp string✅ ISO 8601 datetime when message was sent subscriptionId string✅ Subscription ID this event belongs to eventName string✅ Event name (dot notation by convention; the platform-checked event vocabulary is the closed DataEventType / BulkDataEventType enums) object stringoptional Object name the event relates to payload any✅ Event payload data userId stringoptional User who triggered the event
Event pattern (supports wildcards like "record." or " .created")
Type: string
Property Type Required Description subscriptionId string✅ Unique subscription identifier events string[]✅ Event patterns to subscribe to (supports wildcards, e.g., "record.*", "user.created") objects string[]optional Object names to filter events by (e.g., ["account", "contact"]) filters anyoptional Filter conditions for event payloads (not yet enforced — the runtime filters by object name and event type only) channels string[]optional Channel names for scoped subscriptions
Property Type Required Description messageId string✅ Unique message identifier type 'ping'✅ timestamp string✅ ISO 8601 datetime when message was sent
Property Type Required Description messageId string✅ Unique message identifier type 'pong'✅ timestamp string✅ ISO 8601 datetime when message was sent pingMessageId stringoptional ID of ping message being responded to
Property Type Required Description messageId string✅ Unique message identifier type 'presence'✅ timestamp string✅ ISO 8601 datetime when message was sent presence { userId: string; sessionId: string; status: Enum<'online' | 'away' | 'busy' | 'offline'>; lastSeen: string; … }✅ Presence state
Property Type Required Description userId string✅ User identifier sessionId string✅ Unique session identifier status Enum<'online' | 'away' | 'busy' | 'offline'>✅ Current presence status lastSeen string✅ ISO 8601 datetime of last activity currentLocation stringoptional Current page/route user is viewing device Enum<'desktop' | 'mobile' | 'tablet' | 'other'>optional Device type customStatus stringoptional Custom user status message metadata Record<string, any>optional Additional custom presence data
Property Type Required Description userId string✅ User identifier sessionId string✅ Unique session identifier status Enum<'online' | 'away' | 'busy' | 'offline'>✅ Current presence status lastSeen string✅ ISO 8601 datetime of last activity currentLocation stringoptional Current page/route user is viewing device Enum<'desktop' | 'mobile' | 'tablet' | 'other'>optional Device type customStatus stringoptional Custom user status message metadata Record<string, any>optional Additional custom presence data
Property Type Required Description status Enum<'online' | 'away' | 'busy' | 'offline'>optional Updated presence status currentLocation stringoptional Updated current location customStatus stringoptional Updated custom status message metadata Record<string, any>optional Updated metadata
Property Type Required Description userId string✅ User identifier recordId string✅ Record identifier being edited fieldName string✅ Field name being edited position number✅ Cursor position (character offset from start) selection { start: number; end: number }optional Text selection range (if text is selected)
Property Type Required Description start number✅ Selection start position end number✅ Selection end position
Property Type Required Description userId string✅ User identifier userName string✅ User display name status Enum<'online' | 'away' | 'offline'>✅ User presence status lastSeenAt integer✅ Unix timestamp of last activity in milliseconds lastSeen neveroptional [REMOVED] SimplePresenceState.lastSeen was renamed to lastSeenAt in @objectstack/spec 17 — the last-activity INSTANT now carries the shared EpochMs schema, which declares the epoch-millisecond unit. Rename the key to lastSeenAt; the value is unchanged (Date.now()). Note the neighbouring PresenceState.lastSeen (api/realtime-shared.zod.ts) is a different key with a different type — an ISO-8601 datetime STRING — and is untouched. metadata Record<string, any>optional Additional presence metadata (e.g., current page, custom status)
Property Type Required Description messageId string✅ Unique message identifier type 'subscribe'✅ timestamp string✅ ISO 8601 datetime when message was sent subscription { subscriptionId: string; events: string[]; objects?: string[]; filters?: any; … }✅ Subscription configuration
Property Type Required Description subscriptionId string✅ Unique subscription identifier events string[]✅ Event patterns to subscribe to (supports wildcards, e.g., "record.*", "user.created") objects string[]optional Object names to filter events by (e.g., ["account", "contact"]) filters anyoptional Filter conditions for event payloads (not yet enforced — the runtime filters by object name and event type only) channels string[]optional Channel names for scoped subscriptions
Property Type Required Description messageId string✅ Unique message identifier type 'unsubscribe'✅ timestamp string✅ ISO 8601 datetime when message was sent request { subscriptionId: string }✅ Unsubscribe request
Property Type Required Description subscriptionId string✅ Subscription ID to unsubscribe from
Property Type Required Description subscriptionId string✅ Subscription ID to unsubscribe from
Property Type Required Description url string✅ WebSocket server URL protocols string[]optional WebSocket sub-protocols reconnect booleanoptional (default: true) Enable automatic reconnection reconnectIntervalMs integeroptional (default: 1000) Reconnection interval in milliseconds maxReconnectAttempts integeroptional (default: 5) Maximum reconnection attempts pingIntervalMs integeroptional (default: 30000) Ping interval in milliseconds timeoutMs integeroptional (default: 5000) Message timeout in milliseconds reconnectInterval neveroptional [REMOVED] WebSocketConfig.reconnectInterval was renamed to reconnectIntervalMs in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to reconnectIntervalMs; the value (milliseconds) is unchanged. pingInterval neveroptional [REMOVED] WebSocketConfig.pingInterval was renamed to pingIntervalMs in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to pingIntervalMs; the value (milliseconds) is unchanged. timeout neveroptional [REMOVED] WebSocketConfig.timeout was renamed to timeoutMs in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to timeoutMs; the value (milliseconds) is unchanged. headers Record<string, string>optional Custom headers for WebSocket handshake
Property Type Required Description type Enum<'subscribe' | 'unsubscribe' | 'data-change' | 'presence-update' | 'cursor-update' | 'error'>✅ Event type channel string✅ Channel identifier (e.g., "record.account.123", "user.456") payload any✅ Event payload data occurredAt integer✅ Unix timestamp in milliseconds when the event occurred timestamp neveroptional [REMOVED] WebSocketEvent.timestamp was renamed to occurredAt in @objectstack/spec 17 — the event INSTANT now carries the shared EpochMs schema, which declares the epoch-millisecond unit the bare key name left to the describe prose. Rename the key to occurredAt; the value is unchanged (Date.now()).
This schema accepts one of the following structures:
Type: subscribe
Property Type Required Description messageId string✅ Unique message identifier type 'subscribe'✅ timestamp string✅ ISO 8601 datetime when message was sent subscription { subscriptionId: string; events: string[]; objects?: string[]; filters?: any; … }✅ Subscription configuration
Property Type Required Description subscriptionId string✅ Unique subscription identifier events string[]✅ Event patterns to subscribe to (supports wildcards, e.g., "record.*", "user.created") objects string[]optional Object names to filter events by (e.g., ["account", "contact"]) filters anyoptional Filter conditions for event payloads (not yet enforced — the runtime filters by object name and event type only) channels string[]optional Channel names for scoped subscriptions
Type: unsubscribe
Property Type Required Description messageId string✅ Unique message identifier type 'unsubscribe'✅ timestamp string✅ ISO 8601 datetime when message was sent request { subscriptionId: string }✅ Unsubscribe request
Property Type Required Description subscriptionId string✅ Subscription ID to unsubscribe from
Type: event
Property Type Required Description messageId string✅ Unique message identifier type 'event'✅ timestamp string✅ ISO 8601 datetime when message was sent subscriptionId string✅ Subscription ID this event belongs to eventName string✅ Event name (dot notation by convention; the platform-checked event vocabulary is the closed DataEventType / BulkDataEventType enums) object stringoptional Object name the event relates to payload any✅ Event payload data userId stringoptional User who triggered the event
Type: presence
Property Type Required Description messageId string✅ Unique message identifier type 'presence'✅ timestamp string✅ ISO 8601 datetime when message was sent presence { userId: string; sessionId: string; status: Enum<'online' | 'away' | 'busy' | 'offline'>; lastSeen: string; … }✅ Presence state
Property Type Required Description userId string✅ User identifier sessionId string✅ Unique session identifier status Enum<'online' | 'away' | 'busy' | 'offline'>✅ Current presence status lastSeen string✅ ISO 8601 datetime of last activity currentLocation stringoptional Current page/route user is viewing device Enum<'desktop' | 'mobile' | 'tablet' | 'other'>optional Device type customStatus stringoptional Custom user status message metadata Record<string, any>optional Additional custom presence data
Type: cursor
Property Type Required Description messageId string✅ Unique message identifier type 'cursor'✅ timestamp string✅ ISO 8601 datetime when message was sent cursor { userId: string; sessionId: string; documentId: string; position?: object; … }✅ Cursor position
Property Type Required Description userId string✅ User identifier sessionId string✅ Session identifier documentId string✅ Document identifier being edited position { line: integer; column: integer }optional Cursor position in document selection { start: object; end: object }optional Selection range (if text is selected) color stringoptional Cursor color for visual representation userName stringoptional Display name of user lastUpdate string✅ ISO 8601 datetime of last cursor update
Type: edit
Property Type Required Description messageId string✅ Unique message identifier type 'edit'✅ timestamp string✅ ISO 8601 datetime when message was sent operation { operationId: string; documentId: string; userId: string; sessionId: string; … }✅ Edit operation
Property Type Required Description operationId string✅ Unique operation identifier documentId string✅ Document identifier userId string✅ User who performed the edit sessionId string✅ Session identifier type Enum<'insert' | 'delete' | 'replace'>✅ Type of edit operation position { line: integer; column: integer }✅ Starting position of the operation endPosition { line: integer; column: integer }optional Ending position (for delete/replace operations) content stringoptional Content to insert/replace version integer✅ Document version before this operation timestamp string✅ ISO 8601 datetime when operation was created baseOperationId stringoptional Previous operation ID this builds upon (for OT)
Type: ack
Property Type Required Description messageId string✅ Unique message identifier type 'ack'✅ timestamp string✅ ISO 8601 datetime when message was sent ackMessageId string✅ ID of the message being acknowledged success boolean✅ Whether the operation was successful error stringoptional Error message if operation failed
Type: error
Property Type Required Description messageId string✅ Unique message identifier type 'error'✅ timestamp string✅ ISO 8601 datetime when message was sent code string✅ Error code message string✅ Error message details anyoptional Additional error details
Type: ping
Property Type Required Description messageId string✅ Unique message identifier type 'ping'✅ timestamp string✅ ISO 8601 datetime when message was sent
Type: pong
Property Type Required Description messageId string✅ Unique message identifier type 'pong'✅ timestamp string✅ ISO 8601 datetime when message was sent pingMessageId stringoptional ID of ping message being responded to
subscribeunsubscribeeventpingpongackerrorpresencecursoredit
Property Type Required Description enabled booleanoptional (default: false) Enable WebSocket server path stringoptional (default: "/ws") WebSocket endpoint path heartbeatIntervalMs numberoptional (default: 30000) Heartbeat interval in milliseconds reconnectAttempts numberoptional (default: 5) Maximum reconnection attempts for clients presence booleanoptional (default: false) Enable presence tracking cursorSharing booleanoptional (default: false) Enable collaborative cursor sharing heartbeatInterval neveroptional [REMOVED] WebSocketServerConfig.heartbeatInterval was renamed to heartbeatIntervalMs in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Rename the key to heartbeatIntervalMs; the value (milliseconds) is unchanged.
ObjectStack