diff

Show all changes between current specs and their last versioned snapshots, classified by severity. Unlike breaking, this command always exits 0 and is meant for understanding changes, not gating CI.

Command

contractual diff [--contract <name>] [--format <fmt>] [--severity <level>] [--verbose]

How it works

contractual diff runs the same structural comparison as breaking. It compares each registered contract against its last versioned snapshot and classifies every change as:

breaking: would require a major version bump
non-breaking: would require a minor version bump
patch: backward-compatible fix

The key difference: diff reports all changes and always exits 0. It’s informational, not a gate.

Command	Shows	Exit code
`diff`	All changes	Always 0
`breaking`	All changes	1 if breaking found

Options

Flag	Description	Default
`--contract <name>`	Diff only the named contract. Repeat for multiple.	All contracts
`--format <fmt>`	Output format: `text` or `json`	`text`
`--severity <level>`	Filter changes: `all`, `breaking`, `non-breaking`, `patch`	`all`
`--verbose`	Show JSON Pointer paths for each change	Off

Examples

Show all changes

terminal

$ 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'

order-schema: no changes

Filter to breaking changes only

terminal

$ contractual diff --severity breaking

orders-api: 2 breaking changes — suggested bump: major

BREAKING  Removed endpoint GET /orders/{id}/details
BREAKING  Changed type of field 'amount': string → number

order-schema: no changes

Show verbose output with paths

terminal

$ contractual diff --contract orders-api --verbose

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

BREAKING     Removed endpoint GET /orders/{id}/details
             path: /paths/~1orders~1{id}~1details/get
BREAKING     Changed type of field 'amount': string → number
             path: /components/schemas/Order/properties/amount/type
non-breaking  Added optional field 'tracking_url'
             path: /components/schemas/Order/properties/tracking_url

JSON output for tooling

terminal

$ contractual diff --format json

{
"results": [
  {
    "contract": "orders-api",
    "changes": [
      {
        "path": "/paths/~1orders~1{id}~1details/get",
        "severity": "breaking",
        "category": "endpoint-removed",
        "message": "Removed endpoint GET /orders/{id}/details"
      }
    ],
    "summary": {
      "breaking": 2,
      "nonBreaking": 1,
      "patch": 0
    },
    "suggestedBump": "major"
  }
]
}

Exit codes

Code	Meaning
`0`	Success (regardless of changes found)
`2`	Configuration error
`3`	Tool execution error

When to use diff vs breaking

Scenario	Command
Exploring changes locally	`diff`
Understanding what will be in the changeset	`diff`
Debugging why something was classified as breaking	`diff --verbose`
CI check that blocks PRs	`breaking`
GitHub Action workflow	`breaking` (via Action)

Next steps

breaking: CI gate that fails on breaking changes
Classifications: Full reference for change types
Overview: How the structural differ works