Structured output definition
Structured output is the practice of constraining a language model so its response conforms to a predefined schema, usually JSON Schema, instead of free-form prose. Rather than asking the model to reply in JSON and hoping, the serving layer restricts what tokens it may emit at each step, so the finished response parses and validates against the shape the calling program expects.
Structured output in AI models means the model's answer is forced to match a schema you supply, so downstream code can read it without repair steps or retries. Most APIs take a schema written in application code for a single call and throw it away. In Sanity, the schema an AI instruction writes into is the deployed content model referenced by `schemaId`, so the result lands as a typed document in the Content Lake rather than JSON some service still has to map.
Structured output works through constrained decoding, also called guided generation or grammar-constrained sampling. A language model generates one token at a time, choosing from a probability distribution over its whole vocabulary. Constrained decoding masks out every token that would make the response invalid under your schema, so at each step only schema-legal continuations remain available. The model cannot emit a missing brace, an unexpected key, or an enum value that is not in the list, because those tokens are removed from the running before it picks.
The standard technical reference for this is Willard and Louf's Efficient Guided Generation for Large Language Models (arXiv:2307.09702, 2023), which reframes constrained generation as transitions over a finite-state machine indexed against the model's vocabulary, allowing regex- and grammar-guided decoding with low per-token overhead. That paper underpins the Outlines library and much of the tooling that followed.
From the developer's side the interface is simpler than the mechanism. You pass a JSON Schema alongside the prompt, often generated from a type you already have: a Pydantic model in Python, a Zod object in TypeScript, a Go struct, or a Java class. OpenAI exposes it through `response_format` or `text.format`, and Anthropic through `output_config.format`. Structured output is also offered by Google Gemini, Groq, and Amazon Bedrock.
Structured output guarantees the response matches your schema; JSON mode only guarantees the response is syntactically valid JSON. That is a much weaker promise. In JSON mode a model can return a perfectly well-formed object that is missing a required key, uses a string where you expected a number, or invents an enum value you never defined. Your parser succeeds and your application then fails somewhere less obvious.
OpenAI documents JSON mode as a separate, lesser section on the same structured outputs guide, describing Structured Outputs as the feature that "ensures the model will always generate responses that adhere to your supplied JSON Schema, so you don't need to worry about the model omitting a required key, or hallucinating an invalid enum value." Anthropic puts the same line under constrained decoding: schema-compliant responses, no retries needed for schema violations.
A practical tell for JSON mode is the prompt requirement. Several JSON-mode implementations only work if the word "JSON" appears in your instruction, because the constraint is being applied loosely rather than derived from a schema. Sanity's Prompt action behaves this way: it returns a string by default, and to get JSON you set `format` to `"json"` and include the word JSON in the instruction. That is JSON mode, not schema-constrained decoding, and it is worth knowing which one you are using before you build a parser on top of it.
Prompting for a format and validating afterwards both work, and structured output beats them because it changes when the check happens. "Respond only with JSON, no prose" is a request. The model usually complies and occasionally wraps the object in an apology, a code fence, or a helpful explanation. Constrained decoding is an enforcement applied at decode time, which removes the failure class rather than reducing its rate. Both OpenAI and Anthropic list simpler prompting as a direct benefit, because you stop writing defensive, strongly worded format instructions.
Post-hoc validation plus retry reaches a similar end state by a slower route. You generate, run a JSON Schema validator, and if it fails you send the request again, paying for a second generation in latency and tokens, with a nonzero rate of requests that never succeed within your retry budget. Structured output moves the check from after generation into it.
There is one honest caveat. Vendors document a supported subset of JSON Schema rather than the whole specification. Anthropic's structured outputs page carries sections on JSON Schema limitations, unsupported keywords, regex `pattern` support, property ordering, and schema complexity limits, including additional internal ones. A response can also be cut off by your token limit and arrive incomplete. The guarantee holds inside the supported subset and inside the token budget, which covers most real schemas but is not the same as unconditional.
Whether structured output degrades model quality is genuinely disputed in public, and anyone evaluating it should read both sides rather than trust a single result. Tam et al., in Let Me Speak Freely? A Study on the Impact of Format Restrictions on Performance of Large Language Models (EMNLP 2024 Industry Track), report that stricter output-format restrictions degrade reasoning performance.
dottxt responded in Say What You Mean, re-running the experiments with matched prompts and arguing that the reported degradation comes from prompt design and evaluation choices rather than from structure itself, with structured generation matching or beating free-form output. Later literature, including JSONSchemaBench, cites the two side by side.
A separate point is not disputed at all: a schema constrains shape, not truth. Structured output can return a flawlessly valid object full of facts the model made up. It solves parsing, typing, and integration. It does not solve correctness, and the confidence that well-formed data creates is worth guarding against in any pipeline that writes model results straight into a system of record.
Structured output is about the shape of one model response; structured content is about the shape of information in your system, modeled once and reused by every consumer. The two get conflated constantly, and the gap between them is where AI content pipelines tend to leak. A model can return JSON that validates perfectly against a schema you wrote for that single call and still produce something that fits nowhere in your content model, which leaves an integration layer to map fields, guess at references, and decide what to do with the parts that do not correspond to anything.
Sanity is the Content Operating System for the AI era, the intelligent backend for companies building AI content operations at scale, and the relevance here is that the schema is not a per-call artifact. Sanity's Agent Actions are documented as letting you "programmatically run schema-aware AI instructions to create and modify Sanity documents." Generate requires an uploaded schema: you deploy your content model with `npx sanity@latest schemas deploy` and pass the resulting `schemaId` with every request, so the model writes into typed fields of the same model that the Studio, GROQ queries, and delivery already run on. A `target` narrows the write to specific paths, types, or included and excluded fields, traversing four levels deep by default, and writes land as drafts unless a request explicitly sets `forcePublishedWrite: true`. Agent Actions are documented as an experimental feature whose APIs are subject to change, and they can be run from Functions, webhook listeners, CI/CD pipelines, and migration scripts.
Explore Sanity Today
Understanding structured output is just the beginning. Take the next step and discover how Sanity can enhance your content management and delivery.
Last updated: