JSON report command

Generate a machine-readable JSON report of OpenAPI changes.

Use report when you want a machine-readable JSON representation of the detected changes instead of a terminal or browser view.

Examples:

openapi-changes report ./ sample-specs/petstorev3.json | jq openapi-changes report HEAD~1:openapi.yaml ./openapi.yaml | jq jq is only used here to pretty-print the JSON. If you do not have it installed, remove the pipe and print the raw JSON directly.

You should see something like this:

When to use report

  • Use report when another tool needs structured JSON.
  • Use Summary for a fast terminal overview.
  • Use Markdown Report for a file you can drop into PRs, docs, or release notes.
  • Use HTML Report for the interactive offline UI.

Reproducible output

Use --reproducible when you want JSON output without generated timestamps, for example in golden files or CI snapshots.

openapi-changes report --reproducible ./ sample-specs/petstorev3.json | jq

This mode omits dateGenerated from the JSON output and emits changes in stable semantic order. It keeps rawPath intact so machine consumers still have access to the original engine path when semantic normalization rewrites path.

Partial history output

When you run report against local git history or a GitHub file URL, invalid intermediate revisions are skipped instead of aborting the whole history run, as long as at least one comparable history item can still be rendered.

When that happens, the JSON response includes metaData:

{
  "metaData": {
    "partial": true,
    "skippedCommits": ["abc1234", "def5678"]
  }
}
  • partial tells machine consumers that the history result is incomplete.
  • skippedCommits lists the git or GitHub revision hashes that were skipped during history normalization or rendering.
  • Left/right comparisons do not emit metaData.

If every candidate history item fails, report still exits with an error.

Theme flags

report exposes the shared terminal theme flags in the CLI surface:

openapi-changes report --tektronix ./ sample-specs/petstorev3.json | jq

Most machine-readable workflows simply consume the JSON and ignore terminal presentation.

See Command Arguments for the shared flags.