Skip to content

README.md

Latest commit

 

History

History
111 lines (76 loc) · 3.71 KB

README.md

File metadata and controls

111 lines (76 loc) · 3.71 KB
Raw

Contractual

Contractual

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

license PRs welcome npm downloads

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

License

MIT