Output Reference

This page documents the JSON output schema for unfault review --output json. Useful when parsing CLI output programmatically or building integrations.

Review JSON Output

When you run unfault review --output json, the CLI prints a JSON object with the analysis results.

Top-Level Schema

{
  "meta": { ... },
  "contexts": [ ... ],
  "elapsed_ms": 142
}

Meta Object

{
  "label": "payments-service",
  "languages": ["python"],
  "framework_guesses": ["fastapi"],
  "requested_dimensions": ["stability", "correctness"]
}

Field	Type	Description
`label`	string	Workspace label (usually directory name)
`languages`	array	Detected programming languages
`framework_guesses`	array	Detected frameworks (e.g., `fastapi`, `express`)
`requested_dimensions`	array	Dimensions that were analyzed

Context Object

Each context groups findings together. Currently there is one context per workspace:

{
  "context_id": "ctx_workspace",
  "label": "Workspace",
  "findings": [ ... ]
}

Finding Object

A finding is a pattern detected by a rule:

{
  "id": "python.http.missing_timeout:api/client.py:42",
  "rule_id": "python.http.missing_timeout",
  "kind": "StabilityRisk",
  "title": "HTTP call has no timeout",
  "description": "This HTTP call via requests.get has no timeout specified...",
  "severity": "High",
  "confidence": 0.9,
  "dimension": "stability",
  "file_path": "api/client.py",
  "line": 42,
  "column": 5,
  "end_line": 42,
  "end_column": 45,
  "fix_preview": "Add timeout parameter: requests.get(url, timeout=30)"
}

Field	Type	Description
`id`	string	Unique finding identifier (`rule_id:file_path:line`)
`rule_id`	string	Rule that produced this finding
`kind`	enum	Finding category (see below)
`title`	string	Short title
`description`	string	Detailed explanation
`severity`	enum	`Critical`, `High`, `Medium`, `Low`, `Info`
`confidence`	float	Confidence score (0.0 to 1.0)
`dimension`	string	Which dimension this finding relates to
`file_path`	string	File path where the finding was detected
`line`	integer	Line number (1-based)
`column`	integer \| null	Column number (1-based)
`end_line`	integer \| null	End line number
`end_column`	integer \| null	End column number
`fix_preview`	string \| null	Human-readable summary of suggested fix

Finding Kinds

Kind	Description
`StabilityRisk`	Could cause service instability or outages
`PerformanceSmell`	May impact performance
`BehaviorThreat`	Unexpected behavior under certain conditions
`AntiPattern`	Code pattern that typically leads to problems
`ResourceLeak`	Potential resource leak (connections, memory)
`ReliabilityRisk`	Could affect service reliability
`SecurityVulnerability`	Security concern

Severity Levels

Severity	Description
`Critical`	Immediate action required
`High`	Should be addressed soon
`Medium`	Worth addressing
`Low`	Minor improvement
`Info`	Informational

Dimensions

Dimension	Description
`stability`	Service stability and resilience
`performance`	Execution speed and resource usage
`correctness`	Logic and behavior correctness
`scalability`	Ability to handle increased load
`observability`	Logging, tracing, and monitoring
`reliability`	Consistent operation over time
`security`	Security posture
`maintainability`	Code maintainability

Complete Example

{
  "meta": {
    "label": "payments-service",
    "languages": ["python"],
    "framework_guesses": ["fastapi"],
    "requested_dimensions": ["stability", "correctness"]
  },
  "contexts": [
    {
      "context_id": "ctx_workspace",
      "label": "Workspace",
      "findings": [
        {
          "id": "python.http.missing_timeout:src/client.py:42",
          "rule_id": "python.http.missing_timeout",
          "kind": "StabilityRisk",
          "title": "HTTP call has no timeout",
          "description": "This HTTP call via requests.get has no timeout specified. If the remote service is slow or unresponsive, this call will block indefinitely.",
          "severity": "High",
          "confidence": 0.9,
          "dimension": "stability",
          "file_path": "src/client.py",
          "line": 42,
          "column": 5,
          "fix_preview": "Add timeout parameter: requests.get(url, timeout=30)"
        }
      ]
    }
  ],
  "elapsed_ms": 142
}

Exit Codes

Code	Meaning
0	Success, no findings
1	General error
2	Configuration error
4	Network error
5	Findings detected
6	Invalid input