Event Schemas and Contracts
You'll learn how to define the structure and rules of events so that producers and consumers can evolve independently without breaking each other.
What Are Event Schemas?
An event schema is the blueprint for your event data—it defines what fields are present, their types, and which are required. Think of it like a contract between the event producer and all its consumers: "Here's exactly what I promise to send, and here's what you can count on."
Without schemas, a producer might change an event's structure (renaming a field from userId to user_id), and every consumer breaks silently. Schemas prevent this chaos by making the structure explicit and verifiable.
Core Schema Elements
A well-defined event schema includes:
- Event type/name: What happened? (
OrderPlaced,UserRegistered) - Required fields: Data that must be present (
orderId,timestamp) - Optional fields: Additional context that may be included
- Field types: String, integer, boolean, nested objects, etc.
- Metadata: Event ID, version, correlation IDs for tracing
Versioning Strategies
Systems evolve. Versioning keeps old consumers working while new features are added:
- Additive changes: Adding optional fields is safe—old consumers ignore them
- Version numbers in events: Include
schemaVersion: "2.0"so consumers know what to expect - Maintain backward compatibility: Never remove required fields or change their meaning
- Support multiple versions: Producers may emit both old and new formats during transitions
If you must make breaking changes, treat it as a new event type (OrderPlacedV2) rather than silently changing the existing contract.
Schema Registries
Tools like Apache Avro, JSON Schema, or Protobuf formalize schemas. A schema registry stores and validates these definitions, ensuring producers can't publish malformed events.
Key Takeaway: Event schemas are contracts that define structure, required fields, and versioning rules—enabling producers and consumers to evolve safely across system boundaries.