NOTES / PROMPTING AND CONTEXT ENGINEERING

Structured outputs

Getting machine-readable answers: constrain the response to a JSON schema, validate in code, and retry with the error when it fails.

UPDATED 18 NOV 2026#structured-output#json-schema#validation

Why bother

Downstream code needs data it can parse, not prose. Asking nicely for JSON usually works and sometimes does not; one stray sentence or missing field breaks the pipeline. Structured outputs move the guarantee from the prompt into the API.

Diagram: free text then parse and hope may fail, versus schema and prompt through the model to valid JSON

Diagram: my own.

What the API offers

Anthropic’s documentation describes two complementary features. JSON outputs constrain Claude’s text response to a JSON schema you supply, set through output_config.format, for jobs such as extracting data from text or images, generating structured reports, or formatting API responses. Strict tool use guarantees valid tool parameters1. They can be used independently or together in one request, so an agent can call tools with valid parameters and also return a structured final answer1.

You describe the structure as a JSON schema, or as a type in your language that the SDK converts. The schema follows JSON Schema with some documented limitations, so check the current limits before designing something elaborate1. Other cloud platforms that host Claude also document the feature, so check your platform’s support.

Guaranteed shape is not guaranteed truth

A schema ensures the response parses and has the right fields and types. It cannot ensure the values are correct. A model can return a perfectly valid object containing a wrong date or an invented ID. So:

  1. Validate semantics in code. Check ranges, enums, cross-field rules and, where possible, that IDs exist.
  2. Retry with the error. On failure, return the validation message to the model and try again a bounded number of times, then escalate. See Error handling and recovery.
  3. Log failures. Failure rates are a useful monitoring signal.

Diagram: request, model, validate; on success use it, on failure return the error and retry

Diagram: my own.

Design tips

  • Keep schemas small and flat. Fewer optional branches means fewer chances for odd outputs. Reasoning from experience, not from the docs.
  • Name fields clearly and describe them. Field names and descriptions are part of the prompt.
  • Allow an explicit “unknown”. Offer a null or a status field so the model is not forced to invent a value. This ties to hallucination.
  • Put reasoning before the answer when you need it. Let the model think first, or include a short reasoning field ahead of the verdict; see Reasoning models.
  • If you cannot use the feature, Anthropic’s guide also describes steering format with tagged sections in the prompt, though that carries no guarantee2.

Next: The context window as a budget.

Sources

  1. [1]Structured outputs — Anthropic, Claude Platform docsPARAPHRASED
  2. [2]Prompting best practices — Anthropic, Claude Platform docsPARAPHRASED

© Ashish Kumar. All rights reserved. Quoted and cited material belongs to its owners. How I attribute sources.

Product, company and framework names are trademarks of their respective owners. Mentioning them does not imply affiliation or endorsement.