JSON schemas

Bomly's --format json output follows a stable, versioned schema. Every command shares the same vocabulary — manifests, packages, and findings — described in Architecture → Domain model. These pages are the per-command field references, generated from the source types so they never drift from the binary.

Quick start

Emit JSON instead of the text report, and pipe it to any tool that speaks JSON:

# Pretty-print the whole document
bomly scan . --format json | jq .

# List every package that has at least one vulnerability
bomly scan . --enrich --format json | jq '.packages[] | select(.vulnerabilities | length > 0) | .purl'

# Write the document to a file for a later step
bomly scan . --format json --output scan.json

bomly explain and bomly diff accept the same --format json flag and emit documents that follow their respective schemas above.

Output shape

Every document carries a schema_version and a command, then the three top-level collections:

• manifests[] — detection-stage results, one entry per discovered project, each holding lean dependencies[] (identity, scopes, depends_on, and a package_ref into packages).
• packages[] — matching-stage artifacts, deduplicated by PURL, carrying the enrichment: licenses, vulnerabilities (OSV-aligned, with CVSS/EPSS/reachability), scorecard, and eol.
• findings[] — reference-style audit results that point back at a package (and, for a vulnerability, a specific advisory) rather than copying its data inline.

Enrichment lives once, in packages, and is resolved by PURL — so a CVE that affects a package shared by 50 dependencies appears a single time. See the per-command pages for the exact field-by-field breakdown.

Stability

• schema_version follows semantic versioning. Additive, backward-compatible changes (new optional fields) bump the minor version; a breaking change bumps the major. Pin your consumers to the major version and tolerate unknown fields.
• The schema reference pages are regenerated by make generate, so they always match the binary you are running.

Limitations

• A field is only populated when the corresponding stage ran: vulnerabilities, scorecard, and eol are present only with --enrich; findings only with --audit; reachability only with --analyze.
• An empty vulnerabilities/findings array means nothing was reported under the options you ran with — not a guarantee that the package is safe. In particular, reachability tiers are best-effort; a tier: none/unreachable result is a triage signal, not proof of safety (see Reachability).
• JSON output may contain absolute filesystem paths from the scanned target. Treat a scan document as potentially sensitive before publishing it.