Get Validated JSON Output with --json-schema

When you're building tooling around Claude Code, you often need structured output you can parse reliably. The --output-format json flag gets you JSON, but it doesn't guarantee the shape of that JSON. The --json-schema flag does.

claude -p --json-schema '{
  "type": "object",
  "properties": {
    "bugs": { "type": "array", "items": { "type": "string" } },
    "severity": { "type": "string", "enum": ["low", "medium", "high"] }
  },
  "required": ["bugs", "severity"]
}' "Review this file for bugs: src/auth.ts"

Claude will complete its normal workflow (reading files, reasoning, etc.), then return a final JSON object that matches your schema exactly. If the output doesn't validate, Claude retries until it does.

This is powerful for building automated pipelines where downstream tools expect a specific data shape:

# Extract structured metadata from a codebase
claude -p --json-schema '{
  "type": "object",
  "properties": {
    "language": { "type": "string" },
    "framework": { "type": "string" },
    "entryPoint": { "type": "string" },
    "dependencies": { "type": "array", "items": { "type": "string" } }
  }
}' "Analyse this project and extract its metadata"

The flag only works in print mode (-p), and you can combine it with --output-format json for the full structured response envelope, or use it standalone to get just the validated object.

Define the shape you need, and let Claude fill it in.

via Claude Code CLI Reference