What are structured outputs, and how are they different from JSON mode?

**JSON mode** asks a model to return syntactically valid JSON.\n\n**Structured outputs** constrain the response to a specified schema, such as required fields, types, enumerations, arrays, and nested objects.\n\nUse structured outputs when software must reliably parse the model's response, when extracting records, or when producing arguments for tools. JSON mode alone does not guarantee that required fields exist, values use the correct type, or the object matches the application's contract.\n\nSchema compliance is still not semantic correctness. An output can perfectly match the schema while containing a wrong customer ID, unsupported claim, unsafe amount, or invalid business decision. Application code must validate meaning, permissions, and current state.

Consider an application that expects:\n\n```json\n{\n "decision": "approve | reject | review",\n "confidence": 0.0,\n "reasons": ["string"]\n}\n```\n\nJSON mode may return valid JSON such as:\n\n```json\n{"result": "looks good"}\n```\n\nThe response is parseable but does not satisfy the contract.\n\nStructured outputs use a schema to restrict the generated shape. Depending on the provider and feature, the schema can specify:\n\n- object and array structure;\n- required properties;\n- string, number, integer, boolean, and null types;\n- allowed enumerated values;\n- nested objects;\n- restrictions on additional properties;\n- descriptions that help the model populate fields.\n\nOpenAI's strict function calling guarantees that generated function arguments match the supported JSON Schema definition. Google's Gemini documentation distinguishes structured outputs, which constrain the final answer, from function calling, which requests an application action during a workflow.\n\nUse structured outputs for:\n\n- document and invoice extraction;\n- classification;\n- API-ready records;\n- database staging objects;\n- evaluation labels and scores;\n- UI components;\n- workflow routing;\n- tool arguments;\n- machine-readable research notes.\n\nUse function calling when the model should select an operation for the application to execute. Use structured final output when the model should return a typed result to the application or user. Some workflows use both.\n\nImportant limitations remain:\n\n### Schema support\n\nProviders may support only a subset of JSON Schema. Very complex schemas can become difficult for the model and increase latency or failure rates.\n\n### Refusals and truncation\n\nThe model may refuse, reach an output limit, or stop before completing the structure. Applications must handle incomplete and non-success states.\n\n### Semantic errors\n\nThe schema does not prove that values are true, authorised, current, or internally consistent.\n\n### Injection and security\n\nA malicious document can influence schema-valid values. The application must still treat extracted data as untrusted.\n\n### Versioning\n\nChanging the schema can break downstream consumers. Store a schema or protocol version and test compatibility.\n\n### Validation\n\nEven when a provider advertises strict output, perform local parsing and validation before use. Business rules should include cross-field checks, database lookups, allowed-resource checks, and limits.\n\nA safe flow is:\n\n1. request a strict structured response;\n2. parse it with a typed validator;\n3. reject unknown or unsupported versions;\n4. validate semantics and permissions;\n5. require approval where necessary;\n6. execute through an idempotent application service;\n7. record the raw response, validated object, and outcome.\n\nStructured outputs make model integration more reliable. They do not convert probabilistic generation into trusted business logic.

- [OpenAI — Introducing Structured Outputs](https://openai.com/index/introducing-structured-outputs-in-the-api/) — explains schema-constrained responses, strict function calling, reliability, and limitations. - [OpenAI — Function calling](https://help.openai.com/en/articles/8555517-function-calling-in-the-openai-api) — distinguishes JSON mode from strict schema-matching Structured Outputs. - [Google — Structured outputs](https://ai.google.dev/gemini-api/docs/structured-output) — documents JSON Schema-constrained Gemini responses and supported use cases. - [Google — Using tools](https://ai.google.dev/gemini-api/docs/tools) — distinguishes function calling for intermediate actions from structured final outputs. - [Model Context Protocol — Tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools) — defines JSON Schema input and optional output contracts for interoperable tools.