Configuring breaking changes

Customize breaking changes in your own way.

Not every change that could be breaking is breaking for your API.

openapi-changes lets you customize which changes are flagged as breaking, so you can tailor the rules to match your API’s versioning strategy and consumer expectations.

This feature is available from v0.0.91

How it works

By default, openapi-changes uses libopenapi’s built-in breaking change rules. These rules are sensible defaults that work for most APIs, but sometimes you need more control.

You can override any rule by creating a configuration file called changes-rules.yaml (this is the default config file name).

Using a config file

Explicit config file

Use the --config or -c flag to specify a config file:

openapi-changes summary -c my-rules.yaml old.yaml new.yaml openapi-changes html-report -c ~/configs/strict-rules.yaml ./ specs/openapi.yaml

Auto-detected config

If you don’t specify a config file, openapi-changes automatically looks for changes-rules.yaml in the following places:

  • The current working directory (./changes-rules.yaml)
  • Your home config directory (~/.config/changes-rules.yaml)
If no config file is found in any default location, openapi-changes uses the default breaking rules from libopenapi.

Configuration structure

Each rule in the config file has three options:

  • added is adding this property a breaking change?
  • modified is modifying this property a breaking change?
  • removed is removing this property a breaking change?

Set any option to true (breaking) or false (not breaking).

You only need to specify the rules you want to override. Any rules not specified will use the default values.

Real-world examples

Relaxed mode for deprecation workflows

When you’re deprecating endpoints, removing them isn’t really breaking, your consumers have been warned. This config makes operation and path removals non-breaking:

# changes-rules.yaml - Relaxed rules for deprecation workflows
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false
  patch:
    removed: false
  options:
    removed: false
  head:
    removed: false
  trace:
    removed: false
openapi-changes summary -c deprecation-rules.yaml old.yaml new.yaml

Flexible enum handling

Enum changes are often flagged as breaking, but in practice, adding new enum values is usually safe (consumers should handle unknown values), and removing values might be acceptable in some contexts:

# changes-rules.yaml - Flexible enum handling
schema:
  enum:
    added: false    # Adding new enum values is safe
    removed: false  # Removing enum values is acceptable
    modified: false # Reordering enum values is fine

Strict mode for new APIs

For brand new APIs in active development, you might want stricter rules that flag more changes as breaking to ensure stability:

# changes-rules.yaml - Strict mode for new APIs
schema:
  description:
    modified: true  # Even description changes should be reviewed
  example:
    modified: true  # Example changes could affect consumer tests

operation:
  summary:
    modified: true  # Summary changes need review
  description:
    modified: true  # Description changes need review

Ignoring optional parameter changes

If your API consumers are expected to handle optional parameters gracefully, you can make adding new optional parameters non-breaking:

# changes-rules.yaml - Flexible optional parameters
parameter:
  required:
    modified: false  # Changing required status is acceptable

schema:
  required:
    modified: false  # Schema required changes are acceptable

Full example with multiple overrides

Here’s a comprehensive example combining several common overrides:

# changes-rules.yaml - Production API rules
#
# These rules are tailored for a mature API with:
# - Deprecation workflows (removals are expected)
# - Flexible enum handling (consumers handle unknowns)
# - Strict parameter rules (parameters are contracted)

# Operation/endpoint removals are expected (deprecation workflow)
pathItem:
  get:
    removed: false
  post:
    removed: false
  put:
    removed: false
  delete:
    removed: false
  patch:
    removed: false

# Enum handling - consumers should handle unknown values
schema:
  enum:
    added: false
    removed: false

# Security changes should always be flagged
securityRequirement:
  added: true
  removed: true
  modified: true

Configurable objects

  • paths Path definitions
  • pathItem Operations (get, post, put, delete, patch, etc.)
  • operation Operation details (operationId, requestBody, etc.)
  • parameter Parameter properties (name, required, schema, in)
  • schema Schema properties (type, format, enum, properties)
  • response Response definitions
  • securityScheme Security scheme properties
  • securityRequirement Security requirements on operations
  • header Header definitions
  • mediaType Media type definitions (content types)
  • callback Callback definitions

For the complete list of configurable properties within each component, see the default breaking rules reference in the libopenapi documentation.

What’s next?

Now that you know how to customize breaking change detection, check out: