How to use an output schema in Codex

Automation that reads Codex output needs stable field names and value types. An output schema constrains the final response to a JSON object that another program can validate before using its contents.

JSON Schema describes the response's structure rather than whether its contents match the source data. Required fields, value types, and restrictions on extra properties protect the consumer from an unexpected object; a separate comparison with the input detects a structurally valid but incorrect answer.

You need a working Codex CLI in a Git repository and a model provider that supports structured output. The prompt and any project context must be safe to share with that provider.

1. Create a new file at ./schema.json in your current working directory using your text editor.

   schema.json

   {
     "type": "object",
     "properties": {
       "first_release": {"type": "string"},
       "last_release": {"type": "string"},
       "release_count": {"type": "integer"}
     },
     "required": ["first_release", "last_release", "release_count"],
     "additionalProperties": false
   }

   The path is ./schema.json relative to the directory where you run Codex. If that file already exists, choose an unused filename in both the editor and the Codex command instead of replacing it. All three fields are required; extra fields are rejected, and the count must be an integer rather than a quoted string.
   Related: How to set the working directory for Codex
   Tool: JSON Schema Generator

2. Save ./schema.json.
3. Run Codex with ./schema.json as the output schema.

   $ codex exec --sandbox read-only --output-schema ./schema.json \
     'Generate a fictional release summary.'

   The schema applies to the final assistant response. Progress goes to standard error, while the final response prints to standard output. The read-only sandbox does not grant permission to modify project files.
   Related: How to fix the Codex trusted-directory error
   Related: How to save the last Codex response to a file

4. Check that the final JSON contains two release strings and an integer count.

   {
     "first_release": "2026-11-01",
     "last_release": "2026-11-30",
     "release_count": 30
   }

   first_release and last_release must be strings, while release_count must be an unquoted integer. Generated values, JSON spacing, and property order may vary. A consumer should validate the object against the schema and check its values against the input before using it. Malformed JSON, missing or extra fields, and wrong value types are invalid results; an authentication, unsupported-model, or rejected-schema error is a failed run. The final object is separate from the JSONL event stream enabled by --json.
   Related: How to enable JSON output in Codex