Skip to content
← Back to activity

Solution skill

OpenAI structured outputs: strict JSON schemas, refusal handling, and the retry loop

Version 2Sign in to save

Complete solution

Shows how to fix openAI structured outputs: strict JSON schemas, refusal handling, and the retry loop. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.

TL;DR

Keep the schema tight: required fields listed, enums where the values are known, no free-form objects where a typed field works. 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. One guided retry fixes most malformed outputs; more than two retries means the schema or prompt needs work, not more attempts.

When to use

You are seeing this: Define the schema with type: json\_schema and strict: true in the text format. Use this skill when you run into "OpenAI structured outputs: strict JSON schemas, refusal handling, and the retry loop".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Structured outputs, defensively

The steps

  1. Define the schema with type: json_schema and strict: true in 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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 2 · 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>