Event Schema Design

Event schemas define the stable structure and meaning of data exchanged between services. A well-designed schema lets producers and consumers evolve independently while preserving interoperability.

An event schema describes the fields, types, and semantics of an event published by one service and consumed by others. For example, an `OrderCreated` event might contain an order identifier, customer identifier, creation timestamp, and order lines. The schema is a contract: producers must supply data in the agreed form, while consumers rely on that meaning.

A useful event schema separates the event's identity from its business data. Common metadata includes an event ID, event type, timestamp, and schema version; the payload contains domain-specific information. Names should be unambiguous, field meanings should be documented, and timestamps should use an agreed representation such as ISO-8601 or epoch time.

Compatibility matters because events can remain in queues, logs, or other storage and may be consumed by services deployed at different times. Adding an optional field is generally less disruptive than renaming or removing an existing field. A breaking change should normally use an explicit migration or a new event version/type rather than silently changing the meaning of an existing field.

In Java systems, the schema can be represented by a Java record or class when using a serialization format such as JSON. In larger event-driven systems, a schema registry and formats such as Avro or Protobuf can provide stronger schema management and compatibility checks. The exact tooling is architecture-dependent; the core principle is to treat the event contract as a shared interface between independently deployed components.

Key points

• Treat an event schema as a contract between producers and consumers.
• Give fields precise names, types, and documented meanings.
• Prefer backward-compatible additions over changing or removing established fields.
• Separate event metadata from domain payload data.
• Use explicit versioning or migration strategies for breaking changes.

Interview questions

What is an event schema and why is it important?

An event schema defines the structure and meaning of an event exchanged between services. It specifies fields, data types, and their semantics so different producers and consumers interpret the message consistently. It is important because services can be deployed independently and may depend on the same event for a long time. A stable schema reduces accidental integration failures.

What fields would you typically include in an event?

I would usually include an event identifier, event type, creation timestamp, and the domain payload. Depending on the system, metadata such as a correlation ID, source, or schema version can also be useful. The payload should contain information that consumers need rather than internal implementation details. Every field should have a clear and stable meaning.

How would you evolve an event schema without breaking consumers?

First, I would identify which consumers depend on the existing contract. Adding an optional field is generally safer than removing or renaming an existing field. For a breaking semantic or structural change, I would use an explicit version or a new event contract and migrate consumers deliberately. Automated compatibility checks can help prevent incompatible schemas from being published.

Should an event contain the entire database entity?

Not necessarily. An event should contain the information required for its intended consumers and should represent a meaningful business fact. Exposing an entire database entity can couple consumers to storage details and make future database changes harder. The appropriate payload depends on the event's purpose and the guarantees consumers need.

What is the difference between schema versioning and event versioning?

Schema versioning tracks changes to the structure or rules of a message contract, while event versioning can distinguish different contract variants or event definitions. The exact strategy depends on the serialization technology and compatibility requirements. Some systems keep one event type and evolve its schema compatibly; others publish a new event version or type for breaking changes. The important point is that consumers must be able to determine which contract they are receiving and interpret it correctly.