Request: documented/versioned JSON schema contract for --format=json output (jf audit's shape changed across versions, field disappeared silently)
Nobody has claimed this yet.
- Dominant language
- Go
- Stars
- 595
- Forks
- 307
- Avg merge
- 4d 17h
- Merged PRs (30d)
- 17
Description
Is your feature request related to a problem? Please describe.
We parse jf audit --format=json and jf ca --format=json output directly in an internal tool. Between two captures, we explicitly updated jf from 2.109.0 to 2.120.0. Across that jump, jf audit's JSON shape changed on a clean (zero-violation) scan.
Controlled comparison, same project (private, name redacted here), same run conditions, jf ca --format=json only, diffed byte-for-byte:
jf2.109.0 andjf2.120.0 produced identical output.
So this is not a claim that jf's JSON output is broadly unstable — jf ca held steady across the same version jump. The problem is scoped to jf audit.
Less-controlled comparison — two jf audit --format=json captures of a clean scan, at different jf versions (Fixture A's exact version wasn't recorded, and it's a different project than Fixture B, so this pair has two confounds, not one; noting that plainly rather than glossing over it):
Fixture A (older, version unrecorded):
[
{
"scan_id": "b1977de9-086b-436b-b5da-d433b9d24057",
"violations": [],
"component_id": "<group>:<artifact>:1.0-SNAPSHOT",
"package_type": "Maven",
"status": "completed"
}
]
Fixture B (jf 2.120.0):
[
{
"scan_id": "ad47729c-b7f9-429e-b966-e8880bfeb11d",
"component_id": "root",
"package_type": "generic",
"status": "completed"
}
]
| Field | Fixture A | Fixture B (2.120.0) | Same? |
|---|---|---|---|
violations |
present, [] |
absent entirely | ❌ |
component_id |
real Maven GAV | "root" |
❌ |
package_type |
"Maven" |
"generic" |
❌ |
status |
"completed" |
"completed" |
✅ |
The concerning part isn't any single field value — it's that violations can disappear entirely with no schema-version marker and no changelog signal we could find. A missing violations key is easy for a consumer to misread as "no violations," which is the dangerous direction to be wrong in for a security-scanning command specifically.
Describe the solution you'd like to see
We're not asking you to restore either specific shape above — we don't know which (if either) is "correct." We're asking for a stability contract for --format=json output, starting with jf audit and jf ca:
- A documented, versioned JSON schema per command, and/or
- A schema-version field embedded in the JSON output itself, bumped and changelogged whenever the shape changes
so that scripts, CI pipelines, or agents parsing this output can detect a shape change and fail loudly instead of silently misinterpreting missing/renamed fields.
JFrog CLI version: 2.109.0 → 2.120.0
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by locating the entry points for jf audit --format=json and jf ca --format=json, then compare how their output contracts are currently documented or represented. Done means consumers can identify the schema for each command and detect or follow documented shape changes, including the violations field behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- cli, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 40/100