Not Every Schema Change Is a Breaking Change

Forty lines of diff. Three that mattered. Here is the tool that tells you which three.

The challenge of comparing two versions of a data contract can be overwhelming. The first time I took on this task, I discovered forty lines of differences between the two contracts. Out of those, only three changes would have caused serious issues downstream. It took me nearly twenty minutes to pinpoint those critical differences.

Twenty minutes, for just one contract!

Figure 1: Two contract versions and the recommended merge, in aligned columns.

Figure 2: Every difference flagged as Major/Minor/Patch/Unknown following Open Metadata Difference Standards (OMDS) by Bitol

The problem is not the diff. It is the judgment.

A data contract serves as a promise to those who rely on the data. However, these contracts often undergo edits. Sometimes, producers add new fields, change names, adjust types, or even remove columns that might seem unused. While some edits are harmless, others can disrupt systems relying on that data, especially when everything seems fine at 3 a.m. on a Saturday.

A simple YAML diff won’t clarify which changes are significant. You need to recognize that changing a logical type from string to integer is a more serious issue than merely rewording a description. Being able to make those judgments consistently is difficult, especially when deadlines loom and there’s pressure to deliver before the sprint ends.

To solve this problem, I developed the Schema Drift Advisor, a tool designed to evaluate these changes reliably. Here’s how it works:

Grading Changes: When you input two contract versions, the tool checks each field and categorizes the differences as major, minor, patch, or unknown based on the OMDS specification. Major changes—like dropping required fields or altering logical types—are clearly marked, so you see “three major changes” rather than sifting through forty lines on your own.
Merging Contracts: The tool doesn’t just highlight differences; it also suggests a combined version of the contracts, indicating what the new version number should be. This means you receive actionable insights rather than a list you need to decipher.
Side-by-Side View: You can view both original contracts and the proposed merge side by side, which makes it easier to understand the changes at a glance.

# v1.2.0
properties:
  - name: email
    logicalType: string
    physicalType: varchar(255)

# v1.3.0
properties:
  - name: email
    logicalType: string
    physicalType: varchar(320)

For example, if one version of a contract specifies the `physicalType` for an email field as `varchar(255)` and another as `varchar(320)`, the widening might seem concerning at first glance. However, since the logical type remains unchanged, it’s a minor patch rather than something that would break functionality.

The rules live in a file, not in the code

The severity decisions sit in a YAML rules file that the running service reloads on the fly. Nobody has to rebuild anything to change how a category of change is graded.

This mattered more than I expected. Grading rules are precisely the thing people argue with once they start using a tool like this, and if every disagreement required a rebuild and a redeploy, nobody would have bothered telling me they disagreed.

Try it out!

It is live at tools.actianlabs.com/schema. Just upload any two versions of a contract and see what it finds.

Note: The tool only accepts Open Data Contract Standard (ODCS) YAML files

In the end, it’s about sorting through forty lines to find the three that truly matter—let the tool help you do just that!