OpenAPI Diff Prevents API Breakages
Written by Nikos Vaggalis   
Tuesday, 25 July 2023

OpenAPI Diff, or Oasdiff for short, is an open source utility that takes comparing OpenAPI specs to identify breaking changes to a whole new level.

The consensus is that despite have a multitude of tools available nowadays, designing and maintaining an API is still not an easy task to perform. One of the aspects that causes problems is the dreaded "breaking change". Why is that? Let Oasdiff main implementer and Tufin CTO, Reuven Harrison, explain:

  • What is a breaking change?
    A breaking change is a change to a component, such as a server, that could break a dependent component, such as a client, for example deleting an endpoint. When working with OpenAPI, breaking-changes can be caught by monitoring changes to the specification.
  • Why check for Breaking Changes?
    Detecting breaking changes in OpenAPI is an effective way to avoid downtime and maintain business-continuity, especially for complex applications that involve many APIs, multiple services, large or distributed development teams or undergo frequent changes.

A diff tool can be used to track changes made by developers to APIs, understand their context and impact, provide documentation for API consumers who want to track functionality changes including bug fixes and upgrade paths, and most importantly, to detect breaking-changes and even prevent them.

OpenAPI Diff is a tool that can make that task easy to perform, offering a Java library, a CLI utility, even an online playground for manual comparison, as well as a webservice which you can Curl. It also integrates with the CI/CD pipeline, hence catering for every need and environment out there.

This last part on the CI/CD pipeline is and the most important since automated checking that can detect non-trivial breaking-changes can help to prevent downtime. As such, users can run oasdiff in their CI/CD pipeline as a docker image or a cmd-line to test for breaking-changes and/or break the build on certain conditions. For Github specifically there is also a GitHub action.

The tool's main features are :

  • Detecting breaking changes
  • OpenAPI diff in YAML, JSON, Text/Markdown or HTML
  • Display a user-friendly changelog of all important API changes
  • Run from Docker
  • Embed in your go program
  • OpenAPI diff of local files system or remote files over http/s
  • Compare specs in YAML or JSON format
  • Compare two collections of specs
  • Comprehensive diff including all aspects of OpenAPI Specification: paths, operations, parameters, request bodies, responses, schemas, enums, callbacks, security etc.
  • API deprecation
  • Path prefix modification
  • Path parameter renaming
  • Excluding certain kinds of changes
  • Excluding endpoints
  • Extending breaking-changes with custom checks
  • Localization


Additional improvements in oasdiff’s newest version's breaking-changes:

  • human readable output
  • supports localization for error messages and ignored changes
  • checks can be modified by developers using oasdiff as a library with their own specific checks by adding/removing checks from the slice of checks
  • ability to ignore certain changes with a configuration file
  • support for stability-levels which allows breaking-changes in early development phases like draft and alpha but not later in beta and stable
  • fewer false-positive errors by design
  • improved support for type changes: allows changing integer->number for json/xml properties, allows changing parameters (e. g. query/header/path) to type string from number/integer/etc.
  • allows removal of responses with non-success codes (e. g. , 503, 504, 403)
  • allows adding new content-type to request
  • easier to extend and customize

The tool's many faces:

1. Available on Maven Central as a library:

<groupId>org. openapitools.openapidiff</groupId>

2. Available on Docker Hub as tufin/oasdiff.

3. Available as a Webservice

# download the base spec
curl -o openapi-test1.yaml https://raw.githubusercontent. com/
                 Tufin/oasdiff/main/data/openapi-test1. yaml

# download the revised spec
curl -o openapi-test3.yaml https://raw.githubusercontent. com/
                         Tufin/oasdiff/main/data/openapi-test3. yaml

# check breaking changes by using the web service
curl -X POST \
-F base=@openapi-test1.yaml \
-F revision=@openapi-test3.yaml \

4. Available as an online playground Diff Calculator.

One last thing though. How does it compare to the official OpenApi diff utility? Here's a detailed comparison chart that highlights the differences:






Docker image size 

< 7 MB 

> 80 MB


Deep and comprehensive. Catches every kind of change.

Shallow and partial. 

Ignores some kinds of  


Diff files from local file  




Diff remote files from http 













Colorized Output 



Diff between multiple specs  (using globs)



Breaking Changes 

Full with > 100 checks. 

Specifies exact breaking  changes in human-readable  language.

Partial (# of checks  


Only tells you whether there  were any breaking changes,  doesn't specify the exact  breaking-changes.

Deprecation policies 



Ignore Specific Breaking  Changes with Configuration






In conclusion, Oasdiff's approach to preventing breaking changes is a solid attempt to help in designing and maintaining APIs, as such earning itself a place in the developers' arsenal of most valuable tools.



More Information

OpenAPI Diff Home 


Related Articles

Learn To Protect Your APIs By Hacking Them


To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.


GitLab Adds Google Cloud Integration

GitLab has released public betas of the integration features with Google Cloud that the company announced in 2023. The integration means GitLab’s DevSecOps workflow integrates with Google Cloud secu [ ... ]

Amazon Updates Bedrock With Custom Model Support

Amazon has updated Bedrock, its tool for building with generative AI on AWS. The update adds support for importing custom models and evaluating models, as well as support for using Meta Llama 3 models [ ... ]

More News

raspberry pi books



or email your comment to:

Last Updated ( Tuesday, 25 July 2023 )