Codex Plugin Review Output Schema Structure: Complete Field Reference

The Codex plugin enforces a strict JSON Schema at plugins/codex/schemas/review-output.schema.json that requires four top-level fields: verdict, summary, findings, and next_steps.

The openai/codex-plugin-cc repository defines a machine-verified contract for automated code reviews. Every review result must validate against this schema before the Codex platform accepts it. Understanding this structure is essential for anyone building custom review workflows or debugging validation failures.

Core Review Output Schema Fields

Located at [plugins/codex/schemas/review-output.schema.json](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/schemas/review-output.schema.json), the root object requires exactly four properties with "additionalProperties": false to prevent schema drift.

Required Top-Level Properties

Field	Type	Description
verdict	string (enum: "approve" | "needs-attention")	Overall decision of the review run
summary	string (minLength: 1)	Human-readable high-level assessment
findings	array of objects	Detailed issues discovered in the code
next_steps	array of non-empty strings	Recommended developer actions

Findings Array Structure

Each object in the findings array must contain eight required fields, also with "additionalProperties": false:

Field	Type	Constraints
severity	string	"critical", "high", "medium", or "low"
title	string	minLength: 1
body	string	minLength: 1, full issue description
file	string	minLength: 1, relative file path
line_start	integer	minimum: 1
line_end	integer	minimum: 1
confidence	number	0.0 to 1.0 inclusive
recommendation	string	Suggested fix or mitigation

Valid Review Output Examples

Needs-Attention Example

{
  "verdict": "needs-attention",
  "summary": "Potential security issue detected in authentication module.",
  "findings": [
    {
      "severity": "high",
      "title": "Hard-coded secret",
      "body": "The API key is embedded directly in the source file.",
      "file": "src/auth.js",
      "line_start": 42,
      "line_end": 42,
      "confidence": 0.96,
      "recommendation": "Move the key to an environment variable."
    }
  ],
  "next_steps": [
    "Replace the hard-coded key with `process.env.API_KEY`.",
    "Add a `.env.example` file documenting required env vars."
  ]
}

Approve Example

{
  "verdict": "approve",
  "summary": "All checks passed; code is ready to merge.",
  "findings": [],
  "next_steps": [
    "Run `git push` to submit the changes."
  ]
}

Schema Validation Implementation

The validation logic resides in plugins/codex/scripts/codex-companion.mjs, which loads REVIEW_SCHEMA and rejects any output that fails validation before transmission to the Codex platform.

• Strict mode: "additionalProperties": false at both root and finding levels
• No optional fields: All eight finding properties are required even for minor issues
• Empty findings allowed: Valid when verdict is "approve"

Schema Enforcement in the Review Pipeline

The review command documented at [plugins/codex/commands/review.md](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/commands/review.md) produces output that must conform to this schema. The companion script's validation step prevents malformed reviews from reaching downstream systems.

Summary

• The review output schema is defined in plugins/codex/schemas/review-output.schema.json with four required root fields
• Two verdict values: "approve" signals clean reviews, "needs-attention" triggers developer notification
• Findings require eight fields: severity, title, body, file, line_start, line_end, confidence, and recommendation
• Strict validation: additionalProperties: false prevents extension without schema updates
• Validation occurs in codex-companion.mjs before platform submission

Frequently Asked Questions

What values are valid for the verdict field?

Only "approve" and "needs-attention" are accepted. The enum is hard-coded in the schema at lines 13-17 of review-output.schema.json, and any other value causes validation failure.

Can the findings array be empty?

Yes. An empty array is valid and expected when verdict is "approve". The schema requires the array itself but places no minimum length constraint on its contents.

What happens if a finding omits the confidence field?

Validation fails. All eight finding properties are required per the schema's "required" array. The codex-companion.mjs script will reject the entire review output before it reaches the Codex platform.

Where does schema validation occur in the codebase?

In plugins/codex/scripts/codex-companion.mjs, which loads REVIEW_SCHEMA and validates review output against it. This script runs after the review command completes but before results are transmitted to Codex infrastructure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}