Structured AI Outputs: How to Validate Data Before Saving It or Taking Action

A processable format does not guarantee correct data

A structured output is a model response organized so that an application can interpret it predictably—for example, a JSON object with defined fields and types. It can be useful for extracting data from documents, classifying requests, or preparing information for another component. Its main advantage is that it reduces ambiguity in the format; by itself, it does not turn generated content into a verified fact.

It helps to separate four questions. Can the response be parsed as JSON? Does it have the agreed fields and types? Are its values consistent with one another and with the source information? Is it permitted to use the response for its intended purpose? A response can pass the first checks and fail any of the later ones. An object containing a date in the expected format does not prove that the date appears in the document; a valid category does not prove that the classification is correct.

This distinction also helps you choose an output mechanism. JSON mode or schema-constrained generation is intended to produce a final response in a particular shape. A tool call, by contrast, provides arguments for the application to decide whether to execute an operation. Well-formed arguments do not automatically authorize that operation: execution remains under the control of the system integrating the model.

This guide focuses on the data contract checked on each run. It does not replace the management of changes to models, SDKs, or tools, which requires checking compatibility across versions. Even when the API has not changed, an ambiguous input, an incomplete document, or a misinterpretation can produce a result that should not be saved as confirmed.

Define the contract before writing the prompt

Start with the use that will receive the response, not with a list of fields that seems convenient for the model. If another system must store the result, specify what each field represents, what type it has, and what the application will do with it. A useful contract reduces the risk of different interpretations by the system generating the response and the system consuming it.

For each field, decide whether it is required, optional, or nullable. Do not use an empty string, a made-up value, or zero as a universal substitute for “unknown”: those values can be mistaken for real information. Also define units—for example, whether an amount is expressed in a particular currency—date formats, acceptable bounds, and allowed enumerations. If you have categories, explain what each one means and what to do when none fits.

Business rules usually go beyond types. A schema may allow two amounts to be numbers, while the application may require the total to equal the sum of the line items within a defined tolerance. It may accept a confidence value as a number without establishing an appropriate threshold for confirming a piece of data. Keep these rules explicit rather than assuming that the model will always apply them.

The JSON Schema standard can describe structures and constraints, but a provider's channel may support only a subset of its capabilities. Before relying on a particular keyword, check the current documentation for the model and output mode you have chosen. If a constraint is unavailable in that channel, validate it in the application; do not silently remove it or assume that a prompt instruction will make the model enforce it.

Choose the channel based on the result you need

A structured final output is appropriate when the application needs organized data as its response. JSON mode can guide the overall shape; schema-constrained generation can impose additional constraints if the provider, model, and channel support them. Neither is a universal guarantee of truth, and neither eliminates the need to validate the response received.

Tool calling is useful for proposing arguments to a function known to the application. The workflow does not end when those arguments arrive: the system inspects them, decides whether they can be executed, and performs the operation if appropriate. Keep that separation visible in the design. A field such as “send_payment” should not be an instruction that runs merely because the model produced it.

Before putting an integration into production, check how the channel represents normal results, incomplete responses, and refusals. These states must not be treated as valid objects just because they appear during a transmission or can be partially converted to text. For streamed responses, wait until you have an identifiable final result before making a business decision.

If a schema constraint is unsupported, choose an explicit alternative: validate that constraint locally, simplify the contract without losing essential controls, or switch to a compatible channel. Record the difference. A contract that looks strict in the prompt but is not enforced by the channel can create a false sense of security.

Validate in layers, not with a single check

The first layer is the response state: determine whether you received a processable final response or whether the provider indicated a refusal, interruption, or incomplete result. If the result is truncated or unfinished, do not turn it into a partial acceptance unless your product has explicitly defined and tested that behavior.

The second layer is parsing and structure. Check that the content can be interpreted in the expected format, that the root has the agreed type, and that fields, types, allowed values, and applicable constraints are valid. Do not skip parse-error handling or automatically coerce ambiguous values, such as text to a number, without a documented rule.

The third layer checks meaning and relationships between fields. Verify ranges, consistency, incompatible combinations, and business conditions. The fourth compares the proposal with the original input: an invoice, ticket, or request. When possible, confirm relevant data in the document or in an authorized record. The fifth decides whether the use is permitted: displaying a suggestion does not have the same effect as changing an account or executing an external operation.

Keep the proposed value separate from the confirmed value. If a field needs review, the interface and storage should be able to represent it as pending or unverified. Overwriting the original evidence with a questionable extraction makes it harder to correct the error and reconstruct why a decision was made.

Three practical walkthroughs

The examples below show how a single design distinguishes the shape of a response from its acceptance. The fields are illustrative: a real implementation should adapt them to its documents, accounting rules, taxonomy, and access controls.

blocks

Handle failures in a controlled way

Not every failure calls for the same response. A formatting error may allow a new generation with a narrower instruction. An incomplete response may require another request or a stop. A conflict with the source may need human review. A lack of authorization must block the action; it must not trigger a retry intended to obtain a more convenient answer.

Define in advance when to accept, retry, quarantine, and reject. Limit retries and retain the failed result so you can understand what happened. If the system retries, do not accumulate incompatible responses or simply choose the one that looks most complete. A retry should have a specific purpose—for example, correcting a missing field—and must pass through the same validations again.

Avoid silent corrections that can turn a visible failure into apparently reliable data. Normalizing whitespace or an unambiguous representation may be safe if documented; inventing a missing field, choosing between two contradictory amounts, or adjusting a category to pass a rule is not. Preserve enough information to distinguish the original value from the normalized value.

Test and record the complete workflow

A useful test suite includes ordinary examples and edge cases: missing fields, nulls, out-of-range values, blurry or contradictory documents, categories that do not fit, incomplete responses, and requests that exceed available permissions. Test each stage separately, too. This lets you distinguish a generation-channel failure from a validator error or an overly restrictive business rule.

Measure the proportion of responses usable without intervention, errors by field, detected contradictions, refusals, retries, and cases sent for review. A high schema-conformance rate is not the same as a high semantic-accuracy rate. Keep those metrics separate and compare a sample of accepted results with the original source.

To debug without storing unnecessary data, retain the schema version, the channel and model identifiers where appropriate, the final response state, the result of each validation layer, and the downstream decision. Record the input or a secure reference to it only when data policy allows. Avoid storing sensitive information by default if a reference, technical summary, or error signal is sufficient.

Version the contract and classify its changes. Adding an optional field may be compatible with consumers prepared to ignore it; changing a field's type, changing the meaning of a category, or making an optional field required can break them. Test consumers and migrations before deploying changes, and retain enough trace data to identify which version produced each piece of data.

The final criterion: accept only what has been verified for its intended use

Whether to accept an output depends on its destination. A draft visible to a person may tolerate uncertainty if it is clearly marked; a confirmed accounting record or an external operation requires stricter controls. No single schema resolves these differences: the contract describes the shape, business rules check the meaning, and permissions govern the action.

Before launching the workflow, make sure you can answer what is validated, where it is validated, what evidence supports each value, what happens if a check fails, and who can authorize the next step. If the application cannot distinguish a proposal from verified data and an approved action, it is not yet ready to trust the output.

Keep exploring

Corrections and transparency

If you spot incorrect or outdated information, send us a correction with the page and source we should review.