--json-schema

The --json-schema flag accepts a path to a JSON Schema file and instructs Claude Code to validate its output against that schema before returning. It works in conjunction with --output-format json and -p / --print — the full trio is the standard recipe for producing machine-parseable, schema-guaranteed output from a headless Claude Code invocation.

Without schema enforcement, a pipeline that parses Claude Code's JSON output is making an optimistic assumption: that the model will always return the exact fields, types, and nesting structure the downstream code expects. In practice, models occasionally omit optional fields, wrap objects differently, or include extra keys. Even small deviations break JSON deserializers that expect a rigid structure. The --json-schema flag eliminates this class of runtime error by making the contract explicit and validated at the source.

The schema file itself is a standard JSON Schema document (draft 7 or later). You define the required properties, their types, any enums or patterns, and whether additional properties are permitted. Claude Code uses this schema to constrain the model's output, retrying internally if a generation doesn't conform, and surfacing an error to the caller if it cannot produce a conforming response after reasonable attempts.

A practical example: a PR review pipeline expects every review to include a severity field (one of "low", "medium", "high"), a findings array of objects each with file and message strings, and a boolean approved flag. Without --json-schema, the model might return "severity": "critical" (an unlisted value), breaking the downstream dashboard. With the schema in place, that response is rejected and the model is guided to conform.

This flag is conceptually related to structured-output at the API level — both use JSON Schema to constrain what the model produces — but --json-schema operates at the CLI layer, making it available without any SDK code. It is also closely paired with the CI/CD Structured Output patterns the CCA-F exam draws on, which describe how to combine schema-validated output with incremental review pipelines. When writing a new CI integration, the decision flow is straightforward: non-interactive? add --print. machine-consumed? add --output-format json. rigid contract required? add --json-schema. All three together make the invocation fully deterministic from the consumer's perspective.

Expect scenario questions: "A CI step must write Claude's output to a database without defensive error handling. Which flags are required?" The correct answer always includes --print, --output-format json, and --json-schema. You may also see distractor options that suggest using response prefill or temperature-0 sampling — both wrong approaches on current models.