What Counts as a Breaking Change? A Field Guide

Not all API changes are created equal. Adding a new endpoint is completely safe. Removing one is not. But the line isn't always obvious — especially when it comes to request parameters, response fields, and type changes. Here's a clear taxonomy with examples.

The guiding principle: a change is breaking if it requires existing consumers to update their code in order to avoid errors. A change is safe if consumers can continue using the API exactly as they do today, with no modifications.

Breaking changes

1. Removed endpoint Breaking

Any endpoint that existed in the previous version but is absent in the new version is breaking. Any consumer calling that path will get a 404.

# Before
paths:
  /users/{id}:
    get:
      ...
  /users/{id}/profile:   # ← this endpoint
    get:
      ...

# After — /users/{id}/profile is gone
paths:
  /users/{id}:
    get:
      ...

2. Removed required request parameter Breaking

Wait — why is removing a required parameter breaking? Because consumers are sending it. If the API now returns a 400 for unexpected required fields, those callers break. More commonly, removing it from the spec means the parameter's semantics changed, which is also worth flagging.

3. New required request parameter Breaking

If the new version introduces a required parameter that didn't exist before, consumers who don't send it will get a 400 or 422.

# Before
requestBody:
  required: true
  content:
    application/json:
      schema:
        properties:
          name:
            type: string

# After — "currency" is now required
        properties:
          name:
            type: string
          currency:
            type: string
        required: [name, currency]   # ← breaking

4. Removed response field Breaking

If a field was in the response schema and consumers read it, removing it breaks those consumers.

# Before
responses:
  '200':
    content:
      application/json:
        schema:
          properties:
            id:
              type: string
            legacy_ref:    # ← consumers depend on this
              type: string

# After — legacy_ref is gone

5. Type change on existing field Breaking

Changing a field from integer to string, or from string to an enum with fewer valid values, will break consumers that depend on the original type.

Safe (non-breaking) changes

New optional request parameter Safe

Adding a new parameter with no required: true flag (or adding it to the required array) is safe. Consumers can choose to send it or not.

New endpoint Safe

Consumers who don't know about the new endpoint are completely unaffected.

New response field Safe

As long as consumers deserialise responses permissively (the standard approach), an extra field in the response doesn't break anything.

Documentation-only changes Safe

Changes to description, summary, example, or externalDocs fields don't affect runtime behaviour.

The grey area

Some changes fall between clearly breaking and clearly safe:

• Narrowing enum values — removing a valid enum value from a response field can break consumers that have handling for that value, even if the field itself still exists.
• Making an optional field required — in a response, this is typically safe. In a request, it's breaking.
• Security scheme changes — switching from API key to OAuth is breaking in practice, even if the endpoints are unchanged.

SpecVault currently flags the unambiguously breaking categories. Grey-area changes appear as informational warnings rather than breaking change alerts. We're expanding detection coverage based on feedback from early users.

Using this taxonomy day-to-day

The easiest habit to build: before merging any API change, ask "does this remove something, or add something required?" If the answer is yes to either, flag your consumer teams. If the answer is no — you're adding things, making things optional, or changing docs — you're safe to ship.

And set up SpecVault to catch what you miss.