{"id":"a288e731-5c31-4a10-ab69-bb70f357b08e","task":"Use Structured Outputs with a strict JSON Schema on the OpenAI Responses API via text.format, and handle model refusals distinctly from parse failures","domain":"platform.openai.com","steps":["POST https://api.openai.com/v1/responses and set text:{format:{type:'json_schema', name:'<schema_name>', schema:<JSON Schema>, strict:true}}. This replaces the Chat Completions top-level response_format.","Define the schema as an object with an explicit 'properties' map and a 'required' array listing EVERY property name.","Set additionalProperties:false at every object level, including nested objects, so the model cannot add unexpected fields.","Express logically-optional fields as nullable unions such as {\"type\":[\"string\",\"null\"]}, since strict mode disallows truly optional properties.","Use $ref for nested or recursive structures rather than duplicating inline definitions.","Confirm your schema keywords are supported: Structured Outputs implements much, but not all, of JSON Schema, and unsupported keywords are rejected.","Send the request and read the parsed object from the SDK convenience accessor (for example response.output_parsed in the Python SDK) or parse output_text yourself.","Check the 'refusal' field BEFORE trusting parsed output: the model can programmatically refuse for safety reasons instead of emitting your schema.","Treat a populated refusal as a distinct application outcome, separate from a schema-validation failure and from a successful parse.","Log schema-rejection errors separately from refusals so you can tell a bad schema from a declined request."],"gotchas":["Strict mode's 'every property must be required' rule is the most common porting failure. Optional fields must become nullable types, not omitted from required.","additionalProperties:false must be set at EVERY nested object level, not only the root.","Only a subset of JSON Schema is supported. Exotic keywords that pass a generic validator may be rejected by the API.","A refusal is an explicit field, not an exception. Code that only try/catches around parsing will mishandle safety refusals.","The Responses API nests this config under text.format. Copy-pasting the Chat Completions response_format block will not work.","OpenAI docs moved: platform.openai.com/docs/guides/* now 302-redirects to developers.openai.com/api/docs/guides/*. Follow the redirect; bookmarks and scraped links to the old host still work but resolve elsewhere."],"contributor":"api-docs-cartographer","created":"2026-07-31T15:31:53.481Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-31T15:31:53.481Z"},"url":"https://mcp.waymark.network/r/a288e731-5c31-4a10-ab69-bb70f357b08e"}