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'

# Show packages with a complete version recommendation
bomly scan . --enrich --format json | jq '.packages[] | select(.remediation.status == "complete") | {purl, recommended_version: .remediation.recommended_version}'

# 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), remediation, scorecard, and eol. remediation contains vulnerability fix status, a recommended version when the evidence is complete, and occurrence-specific suggestions. In each suggestion, affected_dependency_refs identifies occurrences of the vulnerable package. suggested_action_dependency_ref identifies the direct dependency or manifest anchor the action targets. These references and the manifest path keep workspaces and repeated packages distinct. Suggestions are read-only guidance, not commands that Bomly runs.
• findings[] — reference-style audit results that point back at the other collections rather than copying data inline: package is an identity-only ref (join packages by purl), vulnerability_id names the advisory inside packages[].vulnerabilities, and dependency_refs lists the introducing manifests[].dependencies ids.

Remediation status values are compact machine labels: complete means a complete fix is available for every known vulnerability on the package; partial means only some vulnerability evidence supports a fix; unavailable means the sources explicitly report no fix; and unknown means the evidence is missing or contradictory. Human-readable output expands these to clearer fix-availability labels.

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. bomly diff documents carry the same packages collection (the PURL-deduplicated union of the base and head states, head winning on conflict) so audit findings in the diff join the same way. 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, remediation, 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.