# Codex Plugin Review Output Schema Structure: Complete Field Reference

> Understand the Codex plugin review output schema structure. Explore the complete field reference for verdict, summary, findings, and next steps, ensuring clear and structured code reviews.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: api-reference
- Published: 2026-08-05

---

**The Codex plugin enforces a strict JSON Schema at [`plugins/codex/schemas/review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/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)](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

```json
{
  "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

```json
{
  "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`](https://github.com/openai/codex-plugin-cc/blob/main/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)](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`](https://github.com/openai/codex-plugin-cc/blob/main/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`](https://github.com/openai/codex-plugin-cc/blob/main/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.