Use a provider’s schema-constrained structured-output feature when your model and endpoint support it, then check the response state, decode the final output, and validate it against your application’s rules. A successful JSON parse proves only that the text is syntactically valid—not that it has the right fields or represents correct data.
What “valid JSON” does—and does not—guarantee
There are three separate checks in a reliable pipeline:
As an Amazon Associate I earn from qualifying purchases.
- Syntax: The output can be decoded as JSON.
- Structure: The decoded value matches the required fields and types.
- Meaning: The values satisfy your application’s rules.
A provider’s JSON mode may address syntax without enforcing your particular schema. Schema-constrained structured output is the better fit when you need a defined object shape, but it still does not establish that the values are semantically correct. Google explicitly recommends validating structured output in application code. Gemini structured outputs documentation
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Define and validate your contract in code
Specify required fields, types, allowed values, ranges, and cross-field rules independently of the prompt. Treat that contract as part of your application, not as an instruction the model can be trusted to follow on its own.
#1 Best Overall
- Check that required fields exist and have the expected types.
- Enforce ranges, enumerated values, and format requirements.
- Check relationships between fields, identifiers, and business rules.
- Reject or route invalid results through an explicit recovery path rather than silently accepting them.
Provider SDKs may offer schema helpers or typed parsing paths, but their supported schema features differ. Check the documentation for the specific provider, model, endpoint, and SDK you use before assuming a schema is portable.
Choose the provider’s structured-output mode
Configuration is provider-specific. The key distinction is whether the feature requests JSON syntax alone or constrains output to a supplied schema.
| Provider | Documented approach | What to verify |
|---|---|---|
| OpenAI | JSON mode for JSON syntax; Structured Outputs for matching a supplied schema. SDK schema helpers are recommended where available. | Model and endpoint support, response state, refusal handling, and the schema helper available in your SDK. OpenAI Structured Outputs documentation |
| Gemini | Structured output configured with a JSON Schema. | Gemini supports a subset of JSON Schema; validate the returned values in your application. Gemini structured outputs documentation |
| Anthropic Claude | JSON schema output configured through output_config.format with type: "json_schema". |
Supported schema features and availability for the target model and API. Claude structured outputs documentation |
Do not copy a request configuration or schema between providers and assume it will behave identically. Each API exposes its own configuration shape and supports its own subset of schema features.
Check the response state before parsing
Inspect the API outcome before handing text to a JSON decoder. A refusal may not follow the requested schema, and an output limit may leave the result incomplete. OpenAI documents both refusal and maximum-token cases as reasons a schema-conforming result may not be available. OpenAI Structured Outputs documentation
For Gemini, reaching a thinking limit can produce an incomplete result with truncated or empty output. Treat this as an incomplete response, not as a malformed object to repair by guessing missing data. Gemini thinking documentation
- Check the HTTP/API status and any provider error details.
- Handle refusal indicators explicitly.
- Check completion or finish state for truncation or incompleteness.
- Only parse when the response contains a complete, usable final output.
Parse the final output, not reasoning content
Thinking-capable models may expose reasoning-related metadata or content separately from the user-facing result. Do not assume every response part is the JSON your application should consume. Parse the documented final output field or output step for the API you are using.
Gemini documents internal reasoning and, in its Interactions API, distinguishes thought steps from output steps. Use the documented output step as the deliverable rather than attempting to parse thought content. Gemini thinking documentation
Decode, validate, and handle failures deliberately
- Receive the response. Check status, refusal state, and completion state first.
- Extract the documented final output. Do not treat reasoning metadata or intermediate steps as the application payload.
- Decode JSON. Use the provider SDK’s documented parsing helper where appropriate, or a trusted JSON decoder.
- Validate the decoded value. Enforce the contract you defined in code, including semantic and cross-field rules.
- Route failures safely. Record or surface refusals, incomplete results, parse failures, and validation failures distinctly. Do not pass partial text downstream as if it were a complete object.
This separation makes failures diagnosable: a parse error is different from a refusal, truncation, schema mismatch, or semantically invalid value. The application can then choose an appropriate retry, user-visible error, or fallback without confusing those cases.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
