A JSON schema embedded directly in a Claude prompt tells the model the exact shape an answer must take before it starts generating, which cuts down on malformed output without requiring a second cleanup pass. This works whether you use Claude’s native output_config.format parameter or simply paste the schema into the prompt text for older integrations. Below is a complete, copy-ready version of both approaches, plus the reasoning behind each part of the schema so you can adapt it instead of just pasting it.
Why “please respond in JSON” isn’t enough
Asking Claude to “respond in JSON” in plain language gets you JSON most of the time, but “most of the time” is not a number you can build a pipeline on. The model can still wrap the object in a markdown code fence, add a sentence of commentary before the braces, use inconsistent key names across calls, or omit a field it judged optional. A parser downstream then throws on the fence, or your code silently reads undefined for a missing key. None of that is really Claude “failing” so much as the instruction being underspecified: the model was never told whether a field is required, what type it should be, or what name it must use.
A JSON schema fixes this by making those decisions explicit and machine-checkable rather than implied by example text. Anthropic’s documented structured outputs feature goes one step further: when you pass a schema through output_config.format, the response is constrained at generation time, not just requested in words, which is a meaningfully different guarantee than prompting alone. It pairs well with a solid system prompt that sets the extraction task up front, rather than trying to carry both the task description and the format requirement in a single user message.
The schema-constrained request, ready to copy
This example extracts structured contact details from a free-text inquiry, a common first step in a sales or support pipeline. It uses Anthropic’s current API shape, which requires the structured-outputs-2025-11-13 beta header when called directly against the raw API.
import json, anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-sonnet-5",
max_tokens=1024,
messages=[{
"role": "user",
"content": "Extract the key information from this email: John Smith "
"(john@example.com) is interested in our Enterprise plan "
"and wants to schedule a demo for next Tuesday at 2pm.",
}],
output_config={
"format": {
"type": "json_schema",
"schema": {
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string", "format": "email"},
"plan_interest": {"type": "string"},
"demo_requested": {"type": "boolean"},
},
"required": ["name", "email", "plan_interest", "demo_requested"],
"additionalProperties": False,
},
}
},
)
text = next(b.text for b in response.content if b.type == "text")
contact = json.loads(text)
Each line in that schema is doing a specific job, and skipping any one of them reopens a specific failure mode:
type: "object"at the root rules out the model returning a bare string, a list, or a single value instead of a keyed structure.propertiesfixes the exact key names. Without it, you’ll seecustomer_nameon one call andnameon the next, because nothing told the model which to prefer."format": "email"on the email field is one of the string formats Claude’s structured outputs support (alongside date-time, uri, uuid, and a few others), and it catches the case where the model paraphrases an address instead of transcribing it.requiredis what turns “the model usually includes this” into “the response will not validate without this.” A missing phone number in the source text should produce an empty string or omitted key only if you designed for that; otherwise, make the field required and let a validation error tell you the extraction failed, rather than finding out three steps downstream.additionalProperties: falseis mandatory for objects in Claude’s current schema support, and it also closes off the model inventing extra keys that nothing in your code expects to read.
What the schema format cannot do
Claude’s structured output modes compared across providers are a useful reference if you’re choosing between Claude, OpenAI, and Gemini for this kind of task, but within Claude specifically, the schema support is a real but bounded subset of the JSON Schema specification, and knowing the boundary up front saves you from designing a schema the API will simply reject. As documented, numeric range constraints such as minimum, maximum, and multipleOf are not supported, and neither are string length constraints like minLength or maxLength. Recursive schemas and external $ref targets are also unsupported. If you need a number capped at a sane range or a string capped at a sane length, that validation still has to happen in your own code after parsing, not inside the schema.
The table below summarizes what’s in bounds versus out of bounds, so you can check a draft schema against it before sending the first request.
| Schema feature | Supported | Practical effect |
|---|---|---|
| object / array / string / integer / number / boolean / null types | Yes | Covers the overwhelming majority of extraction and classification schemas |
enum, const | Yes (strings, numbers, booleans, null only) | Good for fixed category fields like a status or priority label |
| String formats (date-time, email, uri, uuid, ipv4/6, hostname, duration) | Yes | Catches malformed values in common fields without custom regex |
minimum / maximum / multipleOf | No | Range-check numbers yourself after parsing the response |
minLength / maxLength | No | Length-check strings yourself after parsing the response |
Recursive schemas, external $ref | No | Flatten nested self-referencing structures before sending the schema |
Regex pattern | Partial (no backreferences, lookaround, or \b) | Simple patterns work; complex validation regex needs a post-parse check |
Two behaviors are worth planning for even with a valid schema in place. A refusal can still override the schema entirely, reported as stop_reason: "refusal", and you’re billed for that call regardless. Hitting the token limit produces stop_reason: "max_tokens" with output that may be valid-looking but cut off mid-field, so a length check on the raw text before you attempt to parse it as JSON is worth the extra line of code.
A lighter version for prompt-only integrations
If you’re calling Claude through a tool that doesn’t expose output_config, or you’re on an older SDK version, the same discipline still helps even without API-level enforcement. Paste the schema into the prompt as a fenced JSON block and pair it with an explicit instruction naming the format, rather than describing the fields in prose:
Return only a JSON object matching this schema. Do not include any text,
explanation, or markdown fence before or after the object.
{
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string"},
"plan_interest": {"type": "string"},
"demo_requested": {"type": "boolean"}
},
"required": ["name", "email", "plan_interest", "demo_requested"]
}
This prompt-only version is strictly weaker than schema-constrained generation, since nothing stops the model from drifting outside the shape under unusual input. Anthropic’s own prompting guidance on being clear and direct applies directly here: naming the output format explicitly, and explaining why the format matters (a downstream parser, in this case), gives the model more to generalize from than a bare instruction. The same principle shows up in how to write tool descriptions Claude won’t misread â specificity about the contract, not just the goal, is what the model actually uses. Treat the prompt-only version as a fallback for tooling constraints, not a long-term substitute for the schema parameter.
Before and after: the same request, two outcomes
A plain-language request and a schema-constrained request can look similar at a glance but diverge in exactly the cases that break a pipeline. The difference only shows up on the inputs that don’t fit the pattern the model has seen most often.
| Input | Plain-language prompt (“respond in JSON”) | Schema-constrained request |
|---|---|---|
| Email with no phone number mentioned | Sometimes omits the key, sometimes returns null, inconsistently across calls | Field is either required (validation fails loudly, which is correct) or explicitly optional by design |
| Email with extra commentary from the sender | Model occasionally summarizes the commentary into an unrequested extra field | additionalProperties: false prevents extra keys from appearing at all |
| Ambiguous plan name (“your bigger plan”) | Free-text guess, sometimes verbose, sometimes a single word | Still a guess, but constrained to the declared type, so at least it won’t break parsing |
| Model adds a one-line caveat before the JSON | Common; breaks naive JSON.parse() on the raw text | Not possible; the response is the object itself |
That last row is the one worth sitting with. A schema doesn’t make the model smarter about ambiguous input, and it won’t rescue a genuinely bad extraction. What it removes is the formatting noise around a correct or incorrect extraction, so the errors you do see in production are about the content of the answer, not the shape of the envelope it arrived in.
Caching makes the schema cheap to reuse
Compiling a new schema into an enforceable grammar adds latency on first use, and that cost is not hypothetical if you’re sending a different ad hoc schema shape on every call. Anthropic’s documentation notes that compiled grammars are cached for 24 hours from last use, but changing the schema’s structure, or the available tool set, invalidates that cache. In practice, this means a stable, reused schema for a recurring task (like the contact-extraction example above) stays fast, while generating a bespoke schema per request pays the compilation cost every time. If you’re designing a pipeline that calls the same extraction shape repeatedly, keep the schema identical across calls rather than regenerating it dynamically, even if the regenerated version would be functionally equivalent. This stacks with the separate mechanism behind prompt caching breakpoints in the Claude API, which caches the token context rather than the compiled schema grammar.
This is also where prompt caching and schema caching can work together: one caches the instructions and context tokens, the other caches the compiled grammar, and keeping both stable across a batch of similar calls compounds the latency savings rather than just adding them.
A short checklist before you ship a schema-constrained prompt
- Every field your downstream code reads unconditionally is listed under
required, not left to the model’s judgment of what counts as optional. additionalProperties: falseis set on every object in the schema, not just the root.- Numeric ranges and string lengths are validated in your own code after parsing, since the schema format can’t enforce them.
- Your code checks
stop_reasonbefore trusting the output, since bothrefusalandmax_tokenscan produce a response that isn’t the complete object you asked for. - The schema’s structure stays identical across repeated calls to the same task, so the compiled grammar cache actually gets reused.
Featured image: macro photograph of a printed circuit board by Samtoucan, via Wikimedia Commons, licensed under CC BY-SA 3.0.
