OpenAPI contract testing in 2026: oasdiff vs Spectral vs PactFlow (and what I built)

Last year I renamed a field in an API response, switching it from customer_id to customerId. Every test still passed, and the review approved it in around four minutes. Three days later, a mobile team reported a P1 issue because their client had been using customer_id for eighteen months. The pipeline hadn't broken, but the contract between us and them had.

I've spent the past year building tooling to address this issue, and I used most existing tools along the way. Here's what I learned about their strengths and weaknesses.

Contract testing consists of four distinct tasks. The first is identifying if a change breaks anything. OpenAPI specs are compared, and the differences are classified, marking what's incompatible. Removing endpoints, narrowing types, or adding new required fields are all examples of this. The second task is evaluating the quality of the spec itself.

This includes checking for missing descriptions, inconsistent casing, or improperly defined operations. The third task is determining if a specific consumer, known to you, will be affected by the change. For instance, removing an endpoint that three teams depend on would constitute an outage.

The fourth task is deciding whether to block a deployment. This is an organizational decision, with someone determining if a finding should halt a merge and another person capable of overriding it without disabling the entire check. Most tools excel at one or two of these tasks, but few address all four. I built my own tool, SpecShield, to fill this gap.

Job 1 - breaking-change detection - is where oasdiff excels. It's open-source, offers several hundred checks for breaking changes, and provides both a CLI and a GitHub Action. It also features a web-based diff tool where you can paste two specifications side-by-side. If your requirement is simply to know when a PR breaks the spec, installing oasdiff and skipping the rest of this post would suffice. However, breaking-change detection is becoming increasingly commonplace and can't be considered a standalone feature.

Job 2 - linting - is handled well by Spectral and vacuum. Both are free and utilize the same rule format. The ruleset can be extended, allowing you to perform operations like checking for the existence of the operationId or description properties. While both are good, Spectral's lint output can be overwhelming, causing CI checks to fail initially and ultimately being bypassed.