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

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. 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.

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 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:

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:

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 – 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.
• 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 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 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.

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