Skip to content
Wildfire
All tutorials
SampleIllustrative

Version an event contract

Add a field without breaking senders that still emit the previous version.

Topic
Connected operations
Format
Walkthrough
Difficulty
Foundational
Reading time
1 min read (estimate)
Steps
2
Working time
20 min to work through (estimate)

Learning outcome

Choose when a change needs a new version, and how both versions can be read.

Prerequisites

  • A written event type that more than one system uses
Contents, 2 steps

This walkthrough is an authored example of a decision, not a tested migration.

Step 1: Decide whether the change is compatible

Adding an optional field can stay on the same version if old readers ignore it. Removing a field, or changing what a field means, needs a new version.

Checkpoint

You can say whether readers of the current version will still understand the event.

Step 2: Read both versions at the boundary

Accept the versions you still support, and translate them into the shape your system stores. Do not make every downstream worker learn both shapes.

Snippet
export function normalize(event: { version: number; total?: number; amount?: number }) {
  if (event.version === 1) return { amount: event.total ?? 0 };
  return { amount: event.amount ?? 0 };
}

Checkpoint

A version 1 event and a version 2 event both become the stored shape, and an unknown version is rejected.

Review

This guide is an authored example. It hasn't been verified as a complete, production-ready implementation.

Reaching the end of this page marks your reading position, not a verified completion.

Related sample guides

Contact

Have something worth building?

Share a few sentences about what you're trying to change. That's all it takes to start the conversation.

Let's talk