Event Schemas

All events in the MATIH Platform follow a consistent schema defined by the DataPlaneEvent base class. This section documents the event structure, event categories, event chaining, and schema versioning patterns.

DataPlaneEvent Structure

Every event extends the DataPlaneEvent base class:

public class DataPlaneEvent {
    UUID eventId;              // Unique event identifier
    String eventType;          // e.g., "QUERY_COMPLETED"
    EventCategory category;    // Routing category
    String tenantId;           // Tenant scope
    String sourceService;      // Originating service
    String correlationId;      // Request correlation
    UUID parentEventId;        // Parent event (for chains)
    Instant timestamp;         // Event timestamp
    Map<String, Object> payload; // Event-specific data
    Map<String, String> metadata; // Headers and routing info
    String userId;             // User who triggered the event
    int priority;              // Priority level (1-10, default 5)
    String schemaVersion;      // Payload schema version
}

Event Categories

Category	Description	Example Events
`QUERY`	Query execution lifecycle	`QUERY_STARTED`, `QUERY_COMPLETED`, `QUERY_FAILED`
`AGENT`	AI agent events	`INTENT_CLASSIFIED`, `SQL_GENERATED`, `RESPONSE_READY`
`PIPELINE`	Pipeline lifecycle	`PIPELINE_STARTED`, `STEP_COMPLETED`, `PIPELINE_FAILED`
`MODEL`	Semantic model changes	`MODEL_PUBLISHED`, `METRIC_ADDED`
`DASHBOARD`	Dashboard lifecycle	`DASHBOARD_CREATED`, `DASHBOARD_SHARED`
`DATA_QUALITY`	Quality events	`CHECK_PASSED`, `ANOMALY_DETECTED`
`GOVERNANCE`	Policy changes	`POLICY_CREATED`, `ACCESS_REVOKED`
`CATALOG`	Metadata changes	`TABLE_CREATED`, `SCHEMA_UPDATED`
`HEALTH`	Health status	`SERVICE_HEALTHY`, `SERVICE_DEGRADED`
`SYSTEM`	System events	`CONFIG_CHANGED`, `DEPLOYMENT_UPDATED`
`ALERT`	Alert triggers	`THRESHOLD_BREACHED`, `SLA_VIOLATED`

Event Chaining

Events can form chains through the parentEventId field, enabling end-to-end tracing of multi-step workflows:

INTENT_CLASSIFIED (eventId: evt-001)
  |
  +-- SQL_GENERATED (parentEventId: evt-001, eventId: evt-002)
       |
       +-- QUERY_EXECUTED (parentEventId: evt-002, eventId: evt-003)
            |
            +-- RESULTS_ANALYZED (parentEventId: evt-003, eventId: evt-004)
                 |
                 +-- VISUALIZATION_RENDERED (parentEventId: evt-004)

All events in a chain share the same correlationId, making it easy to retrieve the complete chain.

Payload Examples

Query Completed Event

{
  "eventType": "QUERY_COMPLETED",
  "category": "QUERY",
  "tenantId": "acme-corp",
  "sourceService": "query-engine",
  "payload": {
    "queryId": "q-123",
    "sql": "SELECT SUM(amount) FROM orders",
    "rowCount": 1,
    "executionTimeMs": 234,
    "bytesScanned": 1048576
  }
}

Agent Response Event

{
  "eventType": "AGENT_RESPONSE_READY",
  "category": "AGENT",
  "tenantId": "acme-corp",
  "sourceService": "ai-service",
  "payload": {
    "sessionId": "sess-abc",
    "intent": "SQL_QUERY",
    "tokensConsumed": 1523,
    "modelUsed": "gpt-4o",
    "responseTimeMs": 3200
  }
}

Schema Versioning

The schemaVersion field enables backward-compatible payload evolution:

Version	Change	Compatibility
`1.0`	Initial schema	Baseline
`1.1`	Add optional field	Backward compatible
`2.0`	Remove or rename field	Breaking (new consumer version required)

Consumers should ignore unknown fields to maintain forward compatibility.

Kafka Topology -- Topic and partitioning design
CDC Patterns -- Database change events
Service Topology -- Event flows between services

Kafka Topology Redis Pub/Sub