Skip to content
BENIBIX Learn

--json-schema Flag

Also known as claude --json-schema, structured_output

It makes claude -p answer in a JSON shape you set.

Think of it like

It is like a form with boxes. Each answer fills the same boxes.

Example

Emma's job sorts bug reports. With --json-schema, each answer has the same three fields. Her code can file each report without reading the words.

Why it matters

Code downstream can trust the shape, so it does not break on a reply worded a new way.

Definition

--json-schema makes claude -p end with JSON that fits a shape you give it. You pass a JSON Schema, a list of the fields you want and their types. Claude does the task first, then puts an answer that fits in the structured_output field. If your schema is broken, Claude Code stops with an error.

Example code

bash
claude -p "List the functions in auth.py" --output-format json --json-schema '{"type":"object","properties":{"functions":{"type":"array"}}}'
Ask for a list in a fixed shape.
--json-schema shapes the json object on the middle line.

Common mistake

Reading structured_output without checking it is there. If Claude says no to the task, the field is missing.

Key takeaways

  1. 1
    Your shape. As a JSON Schema.
  2. 2
    structured_output. Where it lands.
  3. 3
    Check it exists. It can be missing.

Learn it properly