Breaking Changes

A precise definition of what SpecVault flags as a breaking change — and what it deliberately ignores.

What SpecVault flags as breaking

A breaking change is any change that would cause an existing consumer to fail without modification to their code. SpecVault's diff engine resolves $ref and flattens allOf, so schemas defined under components/ are compared by their actual shape — through nested objects and arrays, across every response status code. Severity is direction-aware: tightening the request contract breaks producers; dropping or changing the response contract breaks consumers.

1. Removed endpoints

An endpoint is a unique combination of HTTP method and path. If an endpoint that existed in version N is absent from version N+1, it's breaking.

# Version 1
paths:
  /users/{id}:
    get: ...      # ← exists
    delete: ...   # ← exists

# Version 2
paths:
  /users/{id}:
    get: ...      # OK
    # delete removed ← BREAKING

2. Removed required request parameters

If a query parameter, path parameter, or header that was required: true in version N is removed entirely from version N+1, consumers sending that parameter will not fail — but it signals an API contract change that may indicate different semantics. SpecVault flags this as breaking because consumers relying on the parameter's effect may observe different behaviour.

3. New required request parameters

Adding a parameter with required: true and no default breaks any consumer that doesn't send it. This is one of the most common breaking changes in practice:

# Version 1
parameters:
  - name: user_id
    in: query
    required: true

# Version 2
parameters:
  - name: user_id
    in: query
    required: true
  - name: tenant_id      # ← NEW
    in: query
    required: true       # ← BREAKING — existing consumers don't send this

4. Removed response fields

If a field that was present in the response schema in version N is absent in version N+1, consumers that read that field will break. SpecVault compares response schemas across every status code, following $ref and allOf into nested objects and array items — not just the top level.

5. Type changes on existing fields

Changing a field's type — for example from string to integer, or from a scalar to an array — breaks consumers that parse the response. SpecVault detects type changes on request parameters, request bodies, and response fields at any depth.

6. Schema-level tightening

Beyond add/remove/type, SpecVault flags changes that narrow what a consumer can rely on:

• Enum values removed from a request — a client sending the old value is now rejected. (Conversely, a value added to a response enum is breaking too — a consumer may not handle it.)
• Format changes on a response field (e.g. date-time → date) that break parsing.
• Tightened request constraints — a smaller maxLength/maximum, a larger minLength/minimum, a new pattern, or any such bound introduced where none existed.
• A response field becoming nullable when it was always present.

7. Deprecation (advisory)

When an operation, parameter, or field gains deprecated: true, SpecVault records it as a non-breaking advisory change so consumers get early warning before the field actually disappears.

What is NOT flagged as breaking

Additive changes are backward-compatible and do not trigger alerts:

• New endpoints — existing consumers don't call them, so they're not affected
• New optional parameters — existing consumers don't send them, and they have defaults or aren't required
• New response fields — existing consumers that don't know about the field will simply ignore it
• Description or documentation changes — changes to description, summary, example, or x- extensions
• New enum values accepted by a request — the server simply accepts more than before. (Note: a new value returned in a response enum is flagged breaking — see category 6.)
• Loosened request constraints — a larger maxLength, a smaller minimum, a removed pattern

The diff result format

Each change in the diff result has five fields:

• severity — breaking or non_breaking
• method — the HTTP method (e.g. GET, POST), or * for a whole-path change
• path — the path template (e.g. /users/{id})
• field — the dotted schema path the change touches (e.g. 200.user.email); empty for structural changes
• description — a human-readable description of the specific change

Known limitations

So you don't over-trust the output:

• Renames aren't paired. A renamed field is reported as a removal (breaking) plus an addition — not a single "renamed" change.
• oneOf / anyOf / discriminator composition isn't deeply compared; only allOf is flattened.
• Severity is a heuristic. Always review the diff before acting on it — the same coverage and limitations are shown in the portal on each service's Changes tab.