JSON schema

Home / Output / JSON schema v1

JSON schema v1

The schema emitted by commitbrief --json. Locked at v1.0.0; v1.x will not change the documented shape.

Top-level

{
  "schema": 1,
  "content": "",
  "findings": [ /* see below */ ],
  "summary": {},
  "meta": { /* see below */ }
}

Field	Type	Notes
schema	int	Always 1. Consumers must refuse if higher than expected.
content	string	Empty on the happy path. Populated only when the LLM produced unparseable output and the pipeline degraded to plain text.
findings	array	Zero or more findings (see below). Empty array means "no issues".
summary	object	Reserved for a future LLM-authored prose summary. Always {} in v1.
meta	object	Provider / model / lang / token / cost / latency block (see below).

Finding

{
  "severity": "high",
  "file": "internal/auth/login.go",
  "line": 42,
  "line_end": 47,
  "title": "Missing nil check on session token",
  "description": "If session is nil here ...",
  "suggestion": "Add `if session == nil { return ErrUnauthenticated }` before line 42.",
  "language": "go",
  "snippet": "+ if user.Authenticate(req.Token) ..."
}

Field	Type	Required?	Notes
severity	string	required	One of critical, high, medium, low, info.
file	string	required	Repo-relative file path.
line	int	required	1-indexed line number in the FILE.
line_end	int	optional	Closed range end; omit (or set ≤ line) for single-line findings.
title	string	required	Short heading.
description	string	required	Multi-sentence explanation of the problem.
suggestion	string	required (since v0.9.0)	The "what should change" prose.
language	string	optional	Language hint for syntax-highlighting the snippet.
snippet	string	optional	Per-line +/-/ prefixed mini-diff illustrating the change.

Important

Consumers MUST ignore unknown fields. New optional fields are allowed within v1.x.

Meta

{
  "provider": "anthropic",
  "model": "claude-opus-4-7",
  "lang": "en",
  "usage": {
    "input_tokens": 2105,
    "output_tokens": 526,
    "cached_input_tokens": 0
  },
  "cost_usd": 0.0834,
  "latency_ms": 4231,
  "cached": false,
  "timestamp": "2026-05-27T18:29:13Z",
  "baselined": 3,
  "suppressed": 1,
  "retry_count": 1,
  "degrade_reason": "prose",
  "filtered_commits": 12
}

Field	Type	Notes
provider	string	Resolved provider name.
model	string	Resolved model identifier.
lang	string	Active locale (en or tr).
usage.input_tokens	int	Prompt tokens billed by the provider.
usage.output_tokens	int	Completion tokens.
usage.cached_input_tokens	int	Cached prompt tokens (Anthropic ephemeral / OpenAI automatic cache).
cost_usd	float	Dollar cost computed from the provider's pricing table. Zero for Ollama / CLI-tool-backed providers.
latency_ms	int64	Round-trip latency in milliseconds. Zero on a local cache hit.
cached	bool	true when the entry was served from the local response cache (no provider call).
timestamp	string (RFC 3339)	When the review completed (or was cached).
baselined	int	Optional (ADR-0027). Present only when non-zero: findings removed because their fingerprint is in the user-private .commitbrief/baseline.json. Removed findings are gone from findings[]; this is the count.
suppressed	int	Optional (ADR-0027). Present only when non-zero: findings removed by an inline commitbrief-ignore marker.
retry_count	int	Optional (ADR-0031). Present only when a repair retry ran: number of repair retries issued on this live review (1). Live-call-only — omitted on a cache hit.
degrade_reason	string	Optional (ADR-0031). Present only when the review degraded to markdown-fallback: one of empty, prose, malformed-json, schema, retry-error. Live-call-only.
filtered_commits	int	Optional (ADR-0035). Present only when the commit filters (--author, --committer, --start-date, --end-date, --text) selected a commit set: how many commits' patches were concatenated into the reviewed diff. Unlike baselined/suppressed this describes what went into the review, not what was removed from findings[]. Omitted on a staged/unstaged/range review.

Degraded output

When the LLM produced unparseable JSON (and the repair-oriented retry — ADR-0031 — also failed), the schema still validates but degrades:

• findings is [] (empty array, type preserved).
• content carries the raw LLM response so downstream tools can inspect what came back.
• A warning: LLM produced malformed JSON; falling back to plain-text view. is emitted on stderr.

Versioning policy

Change	Policy
Add a new optional field (in meta, summary, or Finding)	Allowed in v1.x; not a schema bump.
Add a new key in summary	Allowed; summary is explicitly designed to grow.
Rename, remove, or change the type of a documented field	Breaking — requires schema: 2.

See also

• Output formats — how --json slots into the output system.
• Severity — severity ordering and meaning.
• Exit codes — how --fail-on maps severities to exit codes.