How to use a Codex output schema

Structured integrations benefit from predictable JSON output, especially when responses are parsed by CI jobs, agents, or webhooks. An output schema turns a loosely formatted response into a stable contract, reducing brittle parsing and format drift.

The Codex CLI can validate the final assistant response against a JSON Schema file supplied via --output-schema. When the response JSON does not match the schema, the run fails and reports which fields or types violated the contract.

Strict schemas can increase failure rates while prompts are still evolving, and schema changes require corresponding updates in downstream parsers. Start with only the fields that must always exist, tighten constraints once the shape stabilizes, and treat the schema file as part of the public interface for any automation consuming the response.

1. Create response.schema.json for the response format.

   {
     "type": "object",
     "additionalProperties": false,
     "properties": {
       "summary": { "type": "string" }
     },
     "required": ["summary"]
   }

   Codex output schemas require additionalProperties to be set to false.

2. Validate the schema file is valid JSON before using it.

   $ python3 -m json.tool response.schema.json >/dev/null

   No output indicates the schema is valid JSON.

3. Run Codex with the schema file.

   $ codex exec --output-schema response.schema.json "Return JSON with summary set to OK. Do not run any commands."
   {"summary":"OK"}

   Related: How to fix Codex trusted directory errors

4. Write the final JSON response to a file for downstream tooling.

   $ codex exec --output-schema response.schema.json -o response.json "Return JSON with summary set to OK. Do not run any commands."
   {"summary":"OK"}

   -o writes the final assistant message to response.json while still printing it to stdout.

5. Tighten the schema once the response contract is stable.

   {
     "type": "object",
     "additionalProperties": false,
     "properties": {
       "summary": { "type": "string", "minLength": 1 }
     },
     "required": ["summary"]
   }

   Setting additionalProperties to false rejects any extra fields, including accidental debug keys.

6. Observe the error raised when the schema omits additionalProperties.

   $ codex exec --output-schema response.schema.json "Return JSON with summary."
   ERROR: {
     "error": {
       "message": "Invalid schema for response_format 'codex_output_schema': In context=(), 'additionalProperties' is required to be supplied and to be false.",
       "type": "invalid_request_error",
       "param": "text.format.schema",
       "code": "invalid_json_schema"
     }
   }