Migrating to a new data contract version

Data evolves over time, and as such a data contract needs to support that. We do that by ensuring each data contract has a version.

When it comes to creating a new version, the data producer should be looking to provide a migration path.

What this looks like depends on the size of the change and the criticality of the data. It could range from some documentation, to tools and libraries to aid the migration.

As part of the migration, we may decide to have data produced for both the old version and the new for some time. This allows data consumers to move away from the old version without causing any downtime for their users or customers.

Again, the length of this dual writing depends on the size of the migration, the criticality of the data, and so on.

A migration of a data contract to a new version is really no different to a migration of any interface to a new version, so we can learn by looking at how API migrations are managed, how popular open source libraries manage migrations, and any change management process you may already have in your organisation.