Schema Management
The authoritative definition of every event type's shape — what fields exist, their types, and what they mean.
High-Level Design
Schema Management is the single source of truth every other control depends on.
💼 Business Context
- Without a managed schema, every team's understanding of "what fields does this event have" drifts, and integrations silently break
- Enables self-service: a team can look up an event's schema instead of asking Platform Engineering
- Owned by Platform Engineering, with each event type's business fields owned by the domain team that emits it
🔌 Technical Overview
The Schema Registry is a .NET Core microservice storing JSON Schema definitions for every registered event type, versioned and queryable via a REST API. It's the same schema Validation enforces at ingestion time — a single source of truth rather than two systems that could drift apart. New event types or field additions go through a lightweight registration API call, checked automatically for backward compatibility before being accepted.
Registry Capabilities
💾 Schema Registration
POST /v1/schemas/product_viewed
{
"version": "3",
"fields": {
"product_id": { "type": "string", "required": true },
"price": { "type": "number", "required": true }
}
}
🔗 Integration Points
- Schema Registry API (.NET Core) — the source of truth
- Validation layer (Ingestion) — enforces the registered schema at ingestion time
- Azure Database for PostgreSQL — schema definition storage
- Developer portal — self-service schema lookup for engineering teams
🧰 Services Consumed
- Owning microservice —
Cxos.Processing.SchemaGovernance.Api(see the Full Application Service Map) - Database — Azure Database for PostgreSQL (relational, ACID)
⚠️ Non-Functional Considerations
- Scale: schema lookups are cached aggressively since schemas change far less often than events flow
- Latency: not on the hot path for event processing — validation caches the current schema rather than calling the registry per event
- Reliability: registry unavailability doesn't block ingestion; the last-fetched schema is used until the registry recovers
- Security/Privacy: schema definitions are metadata, not customer data, but field classification (PII tags) is set here and propagates downstream
🎯 Enterprise Example
A new team integrating with CXOS looks up the order_paid event's current schema through the developer portal instead of asking another team or reverse-engineering it from example payloads — cutting integration ramp-up time significantly.