Linting

Linting ensures specs are structurally valid and follow best practices before breaking change detection or changeset generation. Contractual ships with sensible defaults for every supported format.

What linting catches

Category	Examples
Structural errors	Missing required fields, invalid types, malformed YAML/JSON
Reference errors	Broken `$ref` pointers, missing schema definitions
Style violations	Missing descriptions, operations without tags, undocumented parameters
Best practice issues	No servers defined, missing error responses, deprecated patterns

Linting runs independently from breaking change detection. A spec can be structurally valid (passes lint) but still contain breaking changes compared to the previous snapshot.

Supported formats and default linters

Contractual ships with built-in linter defaults for each supported spec format:

Spec type	Default linter	What it checks
OpenAPI	Spectral	OpenAPI spec compliance, style rules
JSON Schema	Built-in validator	Draft-07 compliance, schema validity

Any default can be overridden with a custom command. See Usage for configuration.

When to lint

Run linting at these points in the workflow:

When	Why
Local development	Catch errors before committing
Pre-commit hook	Prevent invalid specs from entering the repo
Pull request CI	Block merges with lint violations
Before breaking check	Ensure valid spec before diffing

Lint vs breaking change detection

These two commands serve different purposes:

Command	Purpose	Compares against
`contractual lint`	Validate spec structure and style	Format specification (OpenAPI, JSON Schema)
`contractual breaking`	Detect API contract changes	Previous snapshot

A valid spec can still contain breaking changes. A spec with lint errors might have no breaking changes. Run both in the CI pipeline.

Next steps

Usage: Command options, custom linters, CI integration