OpenAPI linter and diff CLI

Lint JSON or YAML specs, check diffs, and export SARIF in Python.

Common CLI commands

Zero external packages required on Linux, macOS, and Windows runners.

# Lint YAML or JSON OpenAPI specs with an industry preset
python3 api_validator.py --spec examples/orders-api-good.openapi.yaml --preset stripe-style

# Detect breaking contract changes between two OpenAPI revisions
python3 api_validator.py --diff openapi.base.json openapi.head.json --format markdown

# Export SARIF 2.1.0 for GitHub Code Scanning
python3 api_validator.py --spec openapi.json --format sarif --output api-lint.sarif

Built-in rule presets

Select a baseline profile in presets/ or customize rules in .api-rules.json.

PresetPrimary focusKey rules promoted to error
google-aipURI and resource consistencyADP-002 (kebab-case), ADP-011 (cursors), ADP-017 (operationId)
stripe-stylePayments and developer UXADP-012 (Idempotency-Key), ADP-013 (429), ADP-019 (examples)
owasp-api-top10Security gateADP-010, ADP-014, ADP-015, ADP-016, ADP-021
strict-public-apiZero-warning release gateFails on warnings (fail_on: warning) across naming and docs