Stokoe Event Schema
Canonical event envelope and event types for Stokoe accessibility infrastructure
1. Purpose
The Stokoe Event Schema defines the canonical event envelope structure and core event types for the Stokoe accessibility infrastructure. This schema establishes a unified format for caption events, acoustic events, VoIP events, AI events, policy events, console events, and system events across all Stokoe components.
Events are facts only—they describe what occurred, not what it means or how consumers should react.
2. Goals
- Unified event structure across all Stokoe systems
- Type-safe event definitions for consumers and producers
- Extensible taxonomy organized by capability domain
- Timestamped precision for synchronization
- Vendor-agnostic design with no coupling to specific providers
3. Event Ordering
Events are ordered per session. No global ordering assumptions apply. Consumers must not assume cross-session event ordering. Within a session, events are ordered by occurred_at.
4. Event Envelope (Canonical)
All Stokoe events share this stable envelope structure:
interface StokoeEvent {
schema_version: string // Schema version (e.g., "0.1")
event_id: string // Unique event identifier (UUID)
event_type: string // Canonical event type (namespaced, e.g., "caption.partial")
occurred_at: string // ISO8601 timestamp (e.g., "2026-01-07T14:30:00.000Z")
environment: string // Runtime environment: "dev" | "stage" | "prod"
session_id: string | null // Session identifier (nullable)
user_id: string | null // User identifier (nullable)
source: string // Opaque source identifier; must not be parsed for semantics
severity: string // Observability level: "info" | "warn" | "error"
data?: object // Event-specific payload (optional)
meta?: object // Non-semantic diagnostics only (optional)
}4.1 Field Semantics
| Field | Required | Description |
|---|---|---|
schema_version | Yes | Schema version for compatibility checking |
event_id | Yes | UUID uniquely identifying this event instance |
event_type | Yes | Dot-namespaced canonical event type |
occurred_at | Yes | ISO8601 timestamp when event occurred |
environment | Yes | Deployment environment |
session_id | Yes | Session context (null if not session-scoped) |
user_id | Yes | User context (null if not user-scoped) |
source | Yes | Opaque origin identifier; consumers must not parse or branch on contents |
severity | Yes | Observability severity; not UI priority or user-facing importance |
data | No | Event-type-specific structured payload |
meta | No | Non-semantic diagnostic metadata (e.g., meta.transport); consumers must never branch on meta fields |
5. Event Taxonomy
Events are organized by capability domain using dot-notation namespaces.
5.1 Caption Events (caption.*)
| Event Type | Description | data Fields |
|---|---|---|
caption.partial | Incremental caption token (typewriter mode) | { text: string, offset_ms: number } |
caption.commit | Finalized caption segment | { text: string, start_ms: number, end_ms: number } |
caption.correction | Retroactive caption correction | { original_text: string, corrected_text: string, segment_id: string } |
5.2 Acoustic Events (acoustic.*)
| Event Type | Description | data Fields |
|---|---|---|
acoustic.sound | Non-speech sound classification | { label: string, confidence: number } |
acoustic.overlap | Speaker overlap detection | { speaker_count: number, start_ms: number } |
acoustic.pause | Silence/pause boundary | { duration_ms: number } |
5.3 VoIP Events (voip.*)
| Event Type | Description | data Fields |
|---|---|---|
voip.call_started | Call session initiated | { call_id: string, direction: string } |
voip.call_ended | Call session terminated | { call_id: string, duration_ms: number, reason: string } |
voip.media_connected | Media stream established | { call_id: string, codec: string } |
voip.media_disconnected | Media stream terminated | { call_id: string } |
5.4 AI Events (ai.*)
| Event Type | Description | data Fields |
|---|---|---|
ai.inference_started | Inference request initiated | { request_id: string, model_class: string } |
ai.inference_completed | Inference request completed | { request_id: string, latency_ms: number } |
ai.inference_failed | Inference request failed | { request_id: string, error_code: string } |
5.5 Policy Events (policy.*)
| Event Type | Description | data Fields |
|---|---|---|
policy.limit_reached | Usage limit reached | { limit_type: string, current_value: number, max_value: number } |
policy.access_denied | Access policy denied action | { resource: string, action: string } |
policy.quota_warning | Quota threshold approached | { quota_type: string, percent_used: number } |
5.6 Console Events (console.*)
| Event Type | Description | data Fields |
|---|---|---|
console.session_opened | Console session opened | { client_type: string } |
console.session_closed | Console session closed | { duration_ms: number } |
console.action_invoked | User action invoked | { action_name: string } |
5.7 System Events (system.*)
| Event Type | Description | data Fields |
|---|---|---|
system.session_start | Recognition session initiated | { capabilities: string[] } |
system.session_end | Recognition session terminated | { reason: string } |
system.error | System error or degradation | { error_code: string, component: string } |
system.health_check | Health check result | { status: string, checks: object } |
6. Metadata (meta)
The meta field is reserved for non-semantic diagnostics only. Consumers and motors must never branch on meta contents.
Example permitted uses:
meta.transport— Transport layer identifier (non-semantic)meta.trace_id— Distributed tracing correlationmeta.debug— Debug-only diagnostic data
Values in meta must not include vendor-specific identifiers or semantically meaningful data that would create coupling.
7. Emergency Boundary Note
Events must not contain emergency content, emergency identifiers, or emergency media. Events may only assert boundary conditions (e.g., “session started”, “session ended”) but must not carry emergency-related payload data. Emergency handling occurs outside the event system.
8. Usage
This schema is referenced by:
- Caption Transport Specification (CTS)
- Stokoe Core engine implementations
- Consumer applications (UI, storage, export)
- Observability and monitoring infrastructure
9. Status
Post-ready v0.1. This schema defines the canonical event structure for Stokoe infrastructure.
Implementation status varies across Stokoe components. Consult component-specific documentation for supported event types.