Contractual

Schema contract lifecycle for OpenAPI and JSON Schema
Linting • Breaking change detection • Versioning • Release automation

Docs   •   Quickstart   •   Breaking Detection   •   GitHub Action

Supported Formats: OpenAPI, JSON Schema

Features

• Structural Breaking Change Detection - Compares specs against versioned snapshots using structural diffing, not string comparison. Catches removed fields, type changes, and endpoint deletions.

• Automated Versioning - Changesets declare bump levels (major/minor/patch). contractual version consumes them, bumps versions, updates snapshots, and generates changelogs.

• CI Integration - GitHub Action posts diff tables on PRs, auto-generates changesets, and opens Version PRs for release automation.

• Format Agnostic - Works with OpenAPI and JSON Schema. Custom linters and differs can be configured per contract.

Quick Example

Detect changes

$ contractual diff

orders-api: 3 changes (2 breaking, 1 non-breaking) — suggested bump: major

  BREAKING     Removed endpoint GET /orders/{id}/details
  BREAKING     Changed type of field 'amount': string → number
  non-breaking Added optional field 'tracking_url'

Generate a changeset

$ contractual changeset

? Bump type for orders-api: major
? Summary: Remove deprecated endpoint, change amount type

Wrote .contractual/changesets/fuzzy-lion-dances.md

Bump versions

$ contractual version

orders-api  1.4.2 → 2.0.0 (major)

Updated .contractual/versions.json
Updated CHANGELOG.md

Installation

Development releases are currently available under the npm dev tag. There is no stable release yet. Built-in linting and diffing support OpenAPI and JSON Schema; AsyncAPI and ODCS require custom engines. AI, fixed versioning, and generation hooks are planned. See release scope and contributing.

npm install -g @contractual/cli@dev

Or with other package managers:

pnpm add -g @contractual/cli@dev
yarn global add @contractual/cli@dev

Getting Started

1. Initialize - contractual init scans for specs and creates contractual.yaml
2. Lint - contractual lint validates specs
3. Detect changes - contractual diff shows all changes classified
4. CI gate - contractual breaking fails if breaking changes exist
5. Version - contractual changeset + contractual version for releases

→ Full Quickstart Guide

Community

• Documentation
• GitHub Issues

License

MIT