What Makes an API Change Breaking? A Field-by-Field Guide

Each difference between an old and a new API document lands in one of four buckets. Breaking changes must be treated as breaking releases (or converted into additive changes). Non-breaking changes can ship safely. Potentially-breaking ones need a human call, and informational ones describe value changes rather than shape changes. The detector applies a fixed rule set to every diff; the rules below are exactly the ones it implements.

Breaking

Existing clients will fail to validate, parse or navigate the new response without changes — removed fields, added required fields, removed enum values and type tightenings.

Potentially-breaking

Breakage depends on the client's assumptions — array element removal at a position, a value becoming null, or a null value becoming real.

Non-breaking

Existing, spec-compliant clients keep working — adding an optional field, relaxing a required constraint, adding an enum value or widening a type.

Informational

A factual change in values — scalar value changes, nested structure movement that is better understood at the field level, or array element additions.

Clear-cut breaking changes

• Removing a field — clients that read the previously returned key now get undefined; type-checked serializers can fail at compile time.
• Adding a field to the required list (for schema-style documents) — existing payloads that omit it will fail validation.
• Removing a value from an enum — inputs using the deleted value are rejected outright.
• Tightening a type, including making a nullable value non-null — the set of acceptable values shrinks.
• Object-to-array (or vice versa) — a container shape flip is near-certain breakage.

// before:  "tags": { "primary": "js" }
// after:   "tags": ["js"]            ← breaking

Surprisingly non-breaking changes

• Adding a field that is not required — clients that ignore unknown fields are safe.
• Removing a field from a required list — 'was required, now optional' is a relaxation.
• Adding a new enum value — existing allowed inputs stay valid.
• Widening a type, such as accepting null where only a string was allowed before.

The tricky middle

Some changes depend on the client. A value becoming null (or a null becoming a real value) is flagged potentially-breaking because it only breaks clients that never expected the other side. Removing an element from an array is also potentially-breaking — the element at a given index may have been meaningful, so later elements shift. Scalar value changes are informational by default, unless the value is contractual like a version string or a feature-flag default.

Schema-aware comparison

The detector is more useful on schemas because it can tell required from optional. It recognizes schema-style documents when the root carries type, properties, items, required or enum, and then interprets changes in context: a new entry inside a required list is breaking, an entry removed from it is a relaxation, and a change to an enum's contents is judged by whether values were added or deleted. Plain response samples get the same diff, minus the required/enum context.

The shape-flip radar

Because an object-to-array flip produces a cascade of confusing field-level additions and removals, the detector runs a separate coarse scan that reports the flip itself as a single breaking headline, then suppresses the field-level noise underneath it — you see one clear signal instead of a wall of secondary changes.

Try it

Paste the previous and current versions of your API response or schema into the API Breaking Change Detector to get every change sorted breaking-first, with the exact path and before/after values.