ObjectStackObjectStack

Collaboration

Collaboration protocol schemas

Real-Time Collaboration Protocol

Defines schemas for real-time collaborative editing in ObjectStack.

Supports Operational Transformation (OT), CRDT (Conflict-free Replicated Data Types),

cursor sharing, and awareness state for collaborative applications.

Industry alignment: Google Docs, Figma, VSCode Live Share, Yjs

Source: packages/spec/src/system/collaboration.zod.ts

TypeScript Usage

import { AwarenessEvent, AwarenessSession, AwarenessUpdate, AwarenessUserState, CRDTMergeResult, CRDTState, CRDTType, CollaborationMode, CollaborationSession, CollaborationSessionConfig, CollaborativeCursor, CounterOperation, CursorColorPreset, CursorSelection, CursorStyle, CursorUpdate, GCounter, LWWRegister, ORSet, ORSetElement, OTComponent, OTOperation, OTOperationType, OTTransformResult, PNCounter, TextCRDTOperation, TextCRDTState, UserActivityStatus, VectorClock } from '@objectstack/spec/system';
import type { AwarenessEvent, AwarenessSession, AwarenessUpdate, AwarenessUserState, CRDTMergeResult, CRDTState, CRDTType, CollaborationMode, CollaborationSession, CollaborationSessionConfig, CollaborativeCursor, CounterOperation, CursorColorPreset, CursorSelection, CursorStyle, CursorUpdate, GCounter, LWWRegister, ORSet, ORSetElement, OTComponent, OTOperation, OTOperationType, OTTransformResult, PNCounter, TextCRDTOperation, TextCRDTState, UserActivityStatus, VectorClock } from '@objectstack/spec/system';

// Validate data
const result = AwarenessEvent.parse(data);

AwarenessEvent

Properties

PropertyTypeRequiredDescription
eventIdstring✅Event identifier
sessionIdstring✅Session identifier
eventTypeEnum<'user.joined' | 'user.left' | 'user.updated' | 'session.created' | 'session.ended'>✅Type of awareness event
userIdstringoptionalUser involved in event
timestampstring✅ISO 8601 datetime of event
payloadany✅Event payload

AwarenessSession

Properties

PropertyTypeRequiredDescription
sessionIdstring✅Session identifier
documentIdstringoptionalDocument ID this session is for
usersObject[]✅Active users in session
startedAtstring✅ISO 8601 datetime when session started
lastUpdatestring✅ISO 8601 datetime of last update
metadataRecord<string, any>optionalSession metadata

AwarenessUpdate

Properties

PropertyTypeRequiredDescription
statusEnum<'active' | 'idle' | 'viewing' | 'disconnected'>optionalUpdated status
currentDocumentstringoptionalUpdated current document
currentViewstringoptionalUpdated current view
metadataRecord<string, any>optionalUpdated metadata

AwarenessUserState

Properties

PropertyTypeRequiredDescription
userIdstring✅User identifier
sessionIdstring✅Session identifier
userNamestring✅Display name
userAvatarstringoptionalUser avatar URL
statusEnum<'active' | 'idle' | 'viewing' | 'disconnected'>✅Current activity status
currentDocumentstringoptionalDocument ID user is currently editing
currentViewstringoptionalCurrent view/page user is on
lastActivitystring✅ISO 8601 datetime of last activity
joinedAtstring✅ISO 8601 datetime when user joined session
permissionsstring[]optionalUser permissions in this session
metadataRecord<string, any>optionalAdditional user state metadata

CRDTMergeResult

Properties

PropertyTypeRequiredDescription
stateObject | Object | Object | Object | Object✅Merged CRDT state
conflictsObject[]optionalConflicts encountered during merge

CRDTState

Union Options

This schema accepts one of the following structures:

Option 1

Type: lww-register

Properties

PropertyTypeRequiredDescription
typestring✅
valueany✅Current register value
timestampstring✅ISO 8601 datetime of last write
replicaIdstring✅ID of replica that performed last write
vectorClockObjectoptionalOptional vector clock for causality tracking

Option 2

Type: g-counter

Properties

PropertyTypeRequiredDescription
typestring✅
countsRecord<string, integer>✅Map of replica ID to count

Option 3

Type: pn-counter

Properties

PropertyTypeRequiredDescription
typestring✅
positiveRecord<string, integer>✅Positive increments per replica
negativeRecord<string, integer>✅Negative increments per replica

Option 4

Type: or-set

Properties

PropertyTypeRequiredDescription
typestring✅
elementsObject[]✅Set elements with metadata

Option 5

Type: text

Properties

PropertyTypeRequiredDescription
typestring✅
documentIdstring✅Document identifier
contentstring✅Current text content
operationsObject[]✅History of operations
lamportClockinteger✅Current Lamport clock value
vectorClockObject✅Vector clock for causality

CRDTType

Allowed Values

  • lww-register
  • g-counter
  • pn-counter
  • g-set
  • or-set
  • lww-map
  • text
  • tree
  • json

CollaborationMode

Allowed Values

  • ot
  • crdt
  • lock
  • hybrid

CollaborationSession

Properties

PropertyTypeRequiredDescription
sessionIdstring✅Session identifier
documentIdstring✅Document identifier
configObject✅Session configuration
usersObject[]✅Active users
cursorsObject[]✅Active cursors
versioninteger✅Current document version
operationsObject | Object[]optionalRecent operations
createdAtstring✅ISO 8601 datetime when session was created
lastActivitystring✅ISO 8601 datetime of last activity
statusEnum<'active' | 'idle' | 'ended'>✅Session status

CollaborationSessionConfig

Properties

PropertyTypeRequiredDescription
modeEnum<'ot' | 'crdt' | 'lock' | 'hybrid'>✅Collaboration mode to use
enableCursorSharingboolean✅Enable cursor sharing
enablePresenceboolean✅Enable presence tracking
enableAwarenessboolean✅Enable awareness state
maxUsersintegeroptionalMaximum concurrent users
idleTimeoutinteger✅Idle timeout in milliseconds
conflictResolutionEnum<'ot' | 'crdt' | 'manual'>✅Conflict resolution strategy
persistenceboolean✅Enable operation persistence
snapshotObjectoptionalSnapshot configuration

CollaborativeCursor

Properties

PropertyTypeRequiredDescription
userIdstring✅User identifier
sessionIdstring✅Session identifier
documentIdstring✅Document identifier
userNamestring✅Display name of user
positionObject✅Current cursor position
selectionObjectoptionalCurrent text selection
styleObject✅Visual style for this cursor
isTypingboolean✅Whether user is currently typing
lastUpdatestring✅ISO 8601 datetime of last cursor update
metadataRecord<string, any>optionalAdditional cursor metadata

CounterOperation

Properties

PropertyTypeRequiredDescription
replicaIdstring✅Replica identifier
deltainteger✅Change amount (positive for increment, negative for decrement)
timestampstring✅ISO 8601 datetime of operation

CursorColorPreset

Allowed Values

  • blue
  • green
  • red
  • yellow
  • purple
  • orange
  • pink
  • teal
  • indigo
  • cyan

CursorSelection

Properties

PropertyTypeRequiredDescription
anchorObject✅Selection anchor (start point)
focusObject✅Selection focus (end point)
directionEnum<'forward' | 'backward'>optionalSelection direction

CursorStyle

Properties

PropertyTypeRequiredDescription
colorEnum<'blue' | 'green' | 'red' | 'yellow' | 'purple' | 'orange' | 'pink' | 'teal' | 'indigo' | 'cyan'> | string✅Cursor color (preset or custom hex)
opacitynumber✅Cursor opacity (0-1)
labelstringoptionalLabel to display with cursor (usually username)
showLabelboolean✅Whether to show label
pulseOnUpdateboolean✅Whether to pulse when cursor moves

CursorUpdate

Properties

PropertyTypeRequiredDescription
positionObjectoptionalUpdated cursor position
selectionObjectoptionalUpdated selection
isTypingbooleanoptionalUpdated typing state
metadataRecord<string, any>optionalUpdated metadata

GCounter

Properties

PropertyTypeRequiredDescription
typestring✅
countsRecord<string, integer>✅Map of replica ID to count

LWWRegister

Properties

PropertyTypeRequiredDescription
typestring✅
valueany✅Current register value
timestampstring✅ISO 8601 datetime of last write
replicaIdstring✅ID of replica that performed last write
vectorClockObjectoptionalOptional vector clock for causality tracking

ORSet

Properties

PropertyTypeRequiredDescription
typestring✅
elementsObject[]✅Set elements with metadata

ORSetElement

Properties

PropertyTypeRequiredDescription
valueany✅Element value
timestampstring✅Addition timestamp
replicaIdstring✅Replica that added the element
uidstring✅Unique identifier for this addition
removedboolean✅Whether element has been removed

OTComponent

Union Options

This schema accepts one of the following structures:

Option 1

Type: insert

Properties

PropertyTypeRequiredDescription
typestring✅
textstring✅Text to insert
attributesRecord<string, any>optionalText formatting attributes (e.g., bold, italic)

Option 2

Type: delete

Properties

PropertyTypeRequiredDescription
typestring✅
countinteger✅Number of characters to delete

Option 3

Type: retain

Properties

PropertyTypeRequiredDescription
typestring✅
countinteger✅Number of characters to retain
attributesRecord<string, any>optionalAttribute changes to apply

OTOperation

Properties

PropertyTypeRequiredDescription
operationIdstring✅Unique operation identifier
documentIdstring✅Document identifier
userIdstring✅User who created the operation
sessionIdstring✅Session identifier
componentsObject | Object | Object[]✅Operation components
baseVersioninteger✅Document version this operation is based on
timestampstring✅ISO 8601 datetime when operation was created
metadataRecord<string, any>optionalAdditional operation metadata

OTOperationType

Allowed Values

  • insert
  • delete
  • retain

OTTransformResult

Properties

PropertyTypeRequiredDescription
operationObject✅Transformed operation
transformedboolean✅Whether transformation was applied
conflictsstring[]optionalConflict descriptions if any

PNCounter

Properties

PropertyTypeRequiredDescription
typestring✅
positiveRecord<string, integer>✅Positive increments per replica
negativeRecord<string, integer>✅Negative increments per replica

TextCRDTOperation

Properties

PropertyTypeRequiredDescription
operationIdstring✅Unique operation identifier
replicaIdstring✅Replica identifier
positioninteger✅Position in document
insertstringoptionalText to insert
deleteintegeroptionalNumber of characters to delete
timestampstring✅ISO 8601 datetime of operation
lamportTimestampinteger✅Lamport timestamp for ordering

TextCRDTState

Properties

PropertyTypeRequiredDescription
typestring✅
documentIdstring✅Document identifier
contentstring✅Current text content
operationsObject[]✅History of operations
lamportClockinteger✅Current Lamport clock value
vectorClockObject✅Vector clock for causality

UserActivityStatus

Allowed Values

  • active
  • idle
  • viewing
  • disconnected

VectorClock

Properties

PropertyTypeRequiredDescription
clockRecord<string, integer>✅Map of replica ID to logical timestamp

On this page

TypeScript UsageAwarenessEventPropertiesAwarenessSessionPropertiesAwarenessUpdatePropertiesAwarenessUserStatePropertiesCRDTMergeResultPropertiesCRDTStateUnion OptionsOption 1PropertiesOption 2PropertiesOption 3PropertiesOption 4PropertiesOption 5PropertiesCRDTTypeAllowed ValuesCollaborationModeAllowed ValuesCollaborationSessionPropertiesCollaborationSessionConfigPropertiesCollaborativeCursorPropertiesCounterOperationPropertiesCursorColorPresetAllowed ValuesCursorSelectionPropertiesCursorStylePropertiesCursorUpdatePropertiesGCounterPropertiesLWWRegisterPropertiesORSetPropertiesORSetElementPropertiesOTComponentUnion OptionsOption 1PropertiesOption 2PropertiesOption 3PropertiesOTOperationPropertiesOTOperationTypeAllowed ValuesOTTransformResultPropertiesPNCounterPropertiesTextCRDTOperationPropertiesTextCRDTStatePropertiesUserActivityStatusAllowed ValuesVectorClockProperties