# --json-schema Flag

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

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** claude --json-schema, structured_output

## Think of it like

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

## 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

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.

## 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.

## Why it matters

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

## Common mistake

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

## Three principles

- **Your shape.** As a JSON Schema.
- **structured_output.** Where it lands.
- **Check it exists.** It can be missing.

## Related terms

- [Structured Output (LLM)](https://learn.benibix.com/term/ai/structured-output)
- [--output-format Flag](https://learn.benibix.com/term/ai/output-format-flag)
- [JavaScript Object Notation (JSON)](https://learn.benibix.com/term/development/json)

## Taught in

- [Print Mode Output Flags](https://learn.benibix.com/learn/ai-claude-code-commands/print-mode-output-flags): Claude Code Commands, 14/17

![One answer, three shapes: text, one json object at the end, or a stream-json line per event.](https://learn.benibix.com/diagrams/flag-output-format.svg)

---

Source: https://learn.benibix.com/term/ai/json-schema-flag
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
