Skip to content
Contractual

Introduction

Contractual is a CLI and GitHub Action that orchestrates the schema contract lifecycle: linting, breaking change detection, versioning, and changelog generation for OpenAPI and JSON Schema. Point it at spec files and it detects changes, classifies impact, generates a changeset, bumps versions, and writes changelogs. In CI, it posts a structured diff table on pull requests and opens a “Version Contracts” PR when release is ready.

Who is this for?

Section titled “Who is this for?”

Contractual is for teams that:

  • Publish or internally distribute OpenAPI specs or JSON Schemas
  • Have consumers such as services, SDKs, and clients that depend on compatibility
  • Want automated breaking-change detection in CI instead of manual review
  • Need a reproducible, auditable versioning workflow for contracts

No specific language, framework, or gateway is required. Contractual works with whatever generates or validates schemas.

What does it replace?

Section titled “What does it replace?”

Before Contractual, a typical workflow looks like this:

  • Run breaking change detection manually (or skip it), compare output, decide whether it’s breaking
  • Write a custom shell script to bump a version in some config file
  • Copy-paste changes into a CHANGELOG.md
  • Hope someone remembers to do all this before merging
  • For JSON Schema: write a differ from scratch because nothing existed

Contractual replaces those manual steps with a single CI command and a config file that captures governance rules once.

What it provides

Section titled “What it provides”
  • Lint validation: runs the configured linter (Redocly, Spectral, ajv, or a custom command) against every registered contract on every push
  • Structural breaking change detection: schema-aware diff that classifies every change as breaking, non-breaking, or patch, not a line-by-line text diff
  • Built-in JSON Schema differ: handles field removals, type narrowing, constraint tightening, enum changes, and required-field additions
  • Auto-classified changesets: machine-detected classification saved to a versioned markdown file for review and override before merging
  • Semver versioning: consumes pending changesets, bumps contract versions, updates snapshots, all in one command
  • Changelog generation: per-contract CHANGELOG.md written automatically from changeset descriptions
  • GitHub PR comments: structured diff table posted inline on every pull request that touches a spec
  • Optional AI explanations: set ANTHROPIC_API_KEY and Contractual enriches PR comments and changelog entries with plain-language explanations of what changed and what consumers need to do

How it works

Section titled “How it works”

Contractual uses a two-PR pattern for releasing contract changes:

  1. Change - Edit your spec files locally
  2. Describe - Run contractual changeset to describe the change
  3. Review - Open a PR; the Action validates and posts a diff comment
  4. Release - Merge the Version PR to bump versions and create tags

The CLI is git-agnostic by design. It never commits, tags, or pushes. You control your git history. The GitHub Action handles release automation.

See it in action

Section titled “See it in action”

Here’s what running contractual breaking looks like on a project with two contracts:

$ contractual breaking


✗ orders-api: 2 breaking changes
  BREAKING  Removed endpoint GET /orders/{id}/details
  BREAKING  Changed type of field 'amount': string → number


✓ order-schema: 1 non-breaking change
  MINOR     Added optional field 'shipping_address'


2 breaking changes detected. Exit code 1.

That output drives the PR comment, the changeset classification, and the version bump on merge.

Where to go next

Section titled “Where to go next”

Choose a path based on role.

Maintainer path

Section titled “Maintainer path”

Set up Contractual in the repository, configure governance, and manage releases.

Quickstart

Zero to first working contractual breaking in 5 minutes.

Go to Quickstart

Contributor path

Section titled “Contributor path”

You opened a PR and Contractual left a comment. You want to understand the comment or edit the auto-generated changeset.