# Schema Validation Process for Review Output in Codex: A Technical Deep Dive

> Understand the Codex schema validation process for review output. Codex uses AJV to ensure review data includes essential fields like verdict, summary, and findings.

- Repository: [OpenAI/codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
- Tags: deep-dive
- Published: 2026-07-14

---

**Codex validates every review output against a strict JSON Schema using the AJV validator, ensuring that all generated reviews contain required fields like `verdict`, `summary`, and `findings` before downstream processing.**

The `openai/codex-plugin-cc` repository implements a rigorous validation pipeline to guarantee that review outputs conform to a predictable structure. This schema validation process prevents malformed data from propagating through CI pipelines and ensures that automated tools can reliably parse review results.

## How the Schema Validation Pipeline Works

### Loading and Compiling the JSON Schema

In `plugins/codex/scripts/codex-companion.mjs`, the constant `REVIEW_SCHEMA` points to [`plugins/codex/schemas/review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/schemas/review-output.schema.json). The helper function `readOutputSchema`, located in `plugins/codex/scripts/lib/codex.mjs`, reads this file and compiles it using **AJV**, the popular JSON Schema validator for Node.js.

```js
const REVIEW_SCHEMA = path.join(ROOT_DIR, "schemas", "review-output.schema.json");
const outputSchema = readOutputSchema(REVIEW_SCHEMA);

```

### Schema Structure and Required Fields

The [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json) defines the exact shape of valid review data. Key top-level fields include:

- **`verdict`** – must be one of `"approve"` or `"reject"`
- **`summary`** – free-form text summarizing the review
- **`findings`** – an array of objects containing `severity`, `title`, `body`, `file`, `line_start`, `line_end`, `confidence`, and `recommendation`
- **`next_steps`** – an array of actionable items for the author

The schema enforces data types, required properties, and allowed enum values, making every review output machine-readable.

### Runtime Validation and Error Handling

When a review result is produced, Codex passes the JavaScript object to the compiled AJV validator. If the object conforms to the schema, processing continues; otherwise, AJV throws a validation error that Codex catches and reports to the user.

If validation fails, Codex logs specific AJV error details—such as which property is missing or contains an invalid type—and aborts the review. This prevents downstream components from receiving malformed data.

## Implementation Examples

### Validating Review Output Manually

You can replicate Codex's validation logic in your own scripts:

```js
import fs from "fs";
import path from "path";
import Ajv from "ajv";

const schemaPath = path.join(
  __dirname,
  "..",
  "schemas",
  "review-output.schema.json"
);
const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"));

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

const review = {
  verdict: "approve",
  summary: "All checks passed.",
  findings: [],
  next_steps: []
};

const valid = validate(review);
if (!valid) {
  console.error("Review output is invalid:", validate.errors);
} else {
  console.log("Review output conforms to schema!");
}

```

### Integrating Validation into Review Commands

Hook validation into your review workflow using the internal helper:

```js
import { readOutputSchema } from "./lib/codex.mjs";
import { runReview } from "./review.mjs";

async function reviewCommand(context) {
  const result = await runReview(context);
  const validator = readOutputSchema(REVIEW_SCHEMA);

  if (!validator(result)) {
    throw new Error(
      `Review output does not match schema: ${JSON.stringify(
        validator.errors,
        null,
        2
      )}`
    );
  }

  return result;
}

```

## Key Files in the Validation Process

- **`plugins/codex/scripts/codex-companion.mjs`** – Loads the schema and initializes the AJV validator instance used for every review output.
- **[`plugins/codex/schemas/review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/schemas/review-output.schema.json)** – The JSON Schema definition that specifies required fields, types, and constraints for review results.
- **`plugins/codex/scripts/lib/codex.mjs`** – Contains the `readOutputSchema` helper that reads the schema file and compiles it with AJV.

## Summary

- Codex uses **AJV** to validate review outputs against a strict JSON Schema defined in [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json).
- The `readOutputSchema` function in `lib/codex.mjs` handles schema loading and compilation.
- Required fields include `verdict`, `summary`, `findings`, and `next_steps`, with specific constraints on data types and enum values.
- Validation errors abort the review process and provide detailed feedback about schema violations.
- This pipeline ensures that downstream CI tools and renderers receive well-structured, predictable data.

## Frequently Asked Questions

### What happens if a review output fails schema validation?

Codex catches the AJV validation error and logs detailed information about which properties are missing or invalid. The review process aborts immediately, preventing malformed data from reaching downstream components.

### Which fields are required in the review output schema?

The schema requires a `verdict` (enum: "approve" or "reject"), a `summary` string, an array of `findings` (each containing severity, title, body, file paths, line numbers, confidence, and recommendation), and an array of `next_steps` for actionable items.

### Where is the schema validation logic implemented in the codebase?

The validation logic resides in `plugins/codex/scripts/codex-companion.mjs`, which loads the schema from [`plugins/codex/schemas/review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/plugins/codex/schemas/review-output.schema.json) using the `readOutputSchema` helper defined in `plugins/codex/scripts/lib/codex.mjs`.

### Can I customize the review output schema for my own Codex implementation?

Yes, you can modify [`review-output.schema.json`](https://github.com/openai/codex-plugin-cc/blob/main/review-output.schema.json) to add custom fields or adjust constraints, but you must ensure that the `readOutputSchema` function in `lib/codex.mjs` loads your updated schema and that all review generators produce compatible output.