Schema contract lifecycle

Contractual

Linting, breaking change detection, changesets, versioning, and release automation for OpenAPI and JSON Schema.

Docs Quickstart Lifecycle
Install npm install -g @contractual/cli 
# yaml-language-server: $schema=https://contractual.dev/schema.json

contracts:
  - name: orders-api
    type: openapi
    path: ./specs/orders.openapi.yaml

  - name: order-schema
    type: json-schema
    path: ./schemas/order.schema.json
$ contractual breaking

orders-api (openapi)
  BREAKING  GET /orders/:id/details removed
  BREAKING  amount: string → number
  MINOR     shipping_address added

Exit code: 1
# .contractual/changesets/brave-tigers-fly.md
---
"orders-api": major
"order-schema": minor
---

Removed GET /orders/:id/details.
Added optional shipping_address field.
$ contractual version

Consuming changesets...

  orders-api     1.4.2 → 2.0.0
  order-schema   0.9.1 → 0.10.0

Updated .contractual/versions.json
Updated CHANGELOG.md

Built for schema-driven teams

Contractual works wherever contracts define boundaries.

API-First Development

OpenAPI specs that power REST APIs. Version your public API, generate SDKs, and catch breaking changes before they ship.

orders.openapi.yaml

Event-Driven Systems

JSON Schema for Kafka topics and message queues. Ensure producers and consumers stay compatible as schemas evolve.

order-created.schema.json

Data Contracts

Schema governance for data pipelines. Define contracts between producers and consumers, track changes, and prevent downstream breakage.

customer-events.schema.json

How it works

The two-PR pattern: your specs, your git, automated releases.

1

Change

Edit spec files. Run contractual diff to see impact.

2

Describe

Run contractual changeset. Commit and push.

3

Review

Action posts diff. Reviewers approve the change.

4

Release

Merge Version PR. Tags and releases created automatically.

Git-agnostic by design. The CLI never commits, tags, or pushes. You control your git history. The Action handles release automation. Learn why

Lifecycle flow

Interactive walkthrough across init, lint, breaking, changesets, and releases.

Local
PR
Release

terminal
Project files
1 / 10

Breaking change detection

Structural diffing for OpenAPI and JSON Schema with classification rules.

$ contractual breaking

orders-api (openapi)
  BREAKING  GET /orders/:id/details removed
  BREAKING  amount: string → number
  MINOR     shipping_address added

Exit code: 1
Change Classification
Remove required property Breaking
Narrow type string|number to string Breaking
Add enum constraint Breaking
Decrease maxLength Breaking
Add optional property Minor
Update description Patch
Change Classification
Remove endpoint Breaking
Remove response field Breaking
Add required request field Breaking
Add new endpoint Minor
Add optional request field Minor
Update description or summary Patch
Classification reference

GitHub Action

PR checks with diff comments and automated changesets.

# .github/workflows/contractual.yml
- uses: contractual-dev/contractual@v1
  with:
    mode: pr-check
    github-token: ${{ secrets.GITHUB_TOKEN }}
Action setup