Even when you prompt "answer only in JSON," the model can wrap output in markdown or add commentary that breaks parsing. Structured outputs constrain the response to a defined schema, guaranteeing directly parseable output. This guide covers the two modes, how it works, and pitfalls, grounded in the official docs. (Official: docs.claude.com · as of June 2026)
Why you need it
Forcing JSON with prompt engineering alone leaves problems:
- responses wrapped in markdown code blocks or padded with chatter
- regex parsing breaks the moment the format shifts
- schema violations require error handling and retries
Structured outputs turn this from a "request" into a "guarantee." The official docs recommend this feature over prompt techniques when you always need valid JSON.
Two modes
- JSON output (output_format) — get the whole response in a specified JSON shape. Good for data extraction and structured replies.
- Strict tool use (strict: true) — guarantee that tool names and inputs follow the schema. Good for complex tools and agentic workflows.
You can use them independently or together in one request.
How it is guaranteed
Structured outputs compile your JSON schema into a grammar, then constrain generation so no token can violate those rules (constrained decoding). The model simply cannot produce schema-violating output. More complex schemas take longer to compile, so very large schemas should be simplified.
How to use it
Define the data shape you want as a JSON schema and pass it in.
# Define the desired output shape as a schema
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"price": {"type": "number"},
"in_stock": {"type": "boolean"}
},
"required": ["name", "price"]
}
# Pass this schema via the output_format parameter.
# Check the exact parameter shape and beta header in the official docs.SDKs make it easier: define schemas with Pydantic (Python) or Zod (TypeScript), and the SDK auto-simplifies unsupported constraints (min/max, etc.), reflecting them in descriptions (your code still enforces them).
Things to watch
- Availability/status changes — support varies by model and platform, and some paths may need a beta header. GA status and supported models change, so the official docs are the source of truth.
- Incompatibilities — Citations and message prefilling can't be combined (using citations with it returns a 400).
- Trade-off with extended thinking — if reasoning matters more, extended thinking may fit better. Grammar constraints don't apply to the thinking region.
- Simplify schemas — break overly complex schemas into smaller, simpler ones.
Related guides
For how tool use works, see the Tool Use guide; for the first call, see getting started; for errors/limits, see handling errors and rate limits.
Structured-outputs parameters, beta headers, supported models, and GA status may change; verify the latest in the official docs (docs.claude.com). This site is not an official Anthropic site.