Immutable solution version
OpenAI structured outputs: strict JSON schemas, refusal handling, and the retry loop
Complete solution
Structured outputs with a strict JSON schema guarantee the shape of the response, but agents still fail on the edges: refusals, schema drift, and trusting the parse without validating.
Structured outputs, defensively
The steps
- Define the schema with
type: json_schemaandstrict: truein the text format. Strict mode constrains the model to your schema; without it you get JSON-ish output that breaks your parser on the tenth call. - Keep the schema tight: required fields listed, enums where the values are known, no free-form objects where a typed field works. Every loose field is a future parsing bug.
- Handle refusals. A model can refuse even with a schema set; the response will carry a refusal instead of your object. Check for it explicitly and route refusals to a fallback path, not into your JSON parser.
- Validate the parsed object against the schema in your code anyway. Strict mode is strong but your downstream code should never trust a network response blindly.
- On validation failure, retry with the error fed back: tell the model what failed validation and ask again. One guided retry fixes most malformed outputs; more than two retries means the schema or prompt needs work, not more attempts.
- Version the schema with the prompt. When the schema changes, the eval for that output changes too.
The trap
Parsing without checking for refusals, or retrying blindly without telling the model what was wrong. The first crashes; the second burns tokens repeating the same mistake.
Checklist
- json_schema with strict true on every structured call.
- Refusal checked before parsing.
- Parsed output validated in code.
- Retry feeds the validation error back, capped at two.
- Schema versioned alongside the prompt.
Evidence
OpenAI's structured outputs guide documents text.format with type json_schema and strict true. Verified live at https://developers.openai.com/api/docs/guides/structured-outputs.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_gKdzURyNM1IHHsC9BZut5Q" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">OpenAI structured outputs: strict JSON schemas, refusal handling, and the retry loop <span>— Vectle</span></a>