How to Fix “Invalid schema for response_format” in OpenAI Structured Outputs
Strict mode accepts a subset of JSON Schema. The error tells you which rule you broke and exactly where, if you know how to read it.
On this page
- The fix at a glance
- Read the message first
- 1. Set additionalProperties to false on every object
- 2. Put every property in required, and use null for optional
- 3. Don't put anyOf at the root
- 4. Remove the keywords strict mode doesn't support
- 5. Check you're inside the size limits
- 6. Let the SDK build the schema
- Which way to build the schema
- Match your symptom to the fix
- When it still fails
You turned on Structured Outputs, sent the first request, and got a 400 back before the model saw a word of your prompt. In Python it surfaces as openai.BadRequestError, and the message reads something like this:
Invalid schema for response_format 'MyClass': In context=(), 'additionalProperties' is required to be supplied and to be false.
Or this one, which trips up almost everyone using optional fields:
Invalid schema for response_format 'ReviewSentiment': In context=(), 'required' is required to be supplied and to be an array including every key in properties. Extra required key 'aspect_sentiment' supplied.
Both strings are quoted from issues filed on the openai-python GitHub repository. Your key is fine. Your prompt is fine. The API compared your schema with the subset of JSON Schema that strict mode accepts, and it found a rule you broke.
#The fix at a glance
| What the message says | What it means | Fix |
|---|---|---|
'additionalProperties' is required to be supplied and to be false |
An object allows extra keys | Add "additionalProperties": false to that object |
'required' is required to be supplied and to be an array including every key in properties |
A property isn't listed in required |
List every key, make optional ones nullable |
Extra required key 'x' supplied |
required names a key that isn't in properties |
Fix the typo or add the property |
schema must have a 'type' key |
A property has no type | Add a type |
HTTP 400, code invalid_json_schema |
Often a root-level anyOf |
Wrap the union in an object |
#Read the message first
Every one of these errors has the same 3 parts. You'll get the same message whether you call the API from Python, JavaScript or a raw HTTP request, because the check runs on OpenAI's side. The name in quotes is the schema's name field. If the SDK built the schema from a Pydantic model, it's usually the class name. Then comes the context, then the rule.
The context is the part people skip, and it's the useful bit. An empty context=() means the problem is at the root. A report on the OpenAI developer forum shows a nested failure as context=('properties', 'v1_approach'), which is a path you can walk by hand. Start at the root, open properties, then open v1_approach. That object is the one missing its flag.
I always read the path before I open the schema. It turns a 200-line search into a 2-step lookup. Each message names one rule at one location. So a schema that breaks 4 rules can take 4 round trips, and that's normal, not a sign the fix didn't work.
#1. Set additionalProperties to false on every object
This is the most common cause by a distance. OpenAI's guide says it plainly: Structured Outputs only generates the keys you specify, so you must set additionalProperties: false to opt in. The rule applies to every object in the schema. That includes nested objects, objects inside array items, and anything under $defs.
The usual trap is a schema generated by a library. Pydantic's model_json_schema() only emits "additionalProperties": false when the model forbids extra fields. Without that setting, every nested model you reference arrives without the flag. You fix the root, resend, and the error simply moves one level down. If you have 6 nested models, you can see 6 errors in a row unless you fix them all at once.
The fix is mechanical, so I'd rather write a walker than trust my eyes on a large schema. A dozen lines will do it:
def check(node, path=()):
if isinstance(node, dict):
if node.get("type") == "object" or "properties" in node:
props = set(node.get("properties", {}))
req = set(node.get("required", []))
if node.get("additionalProperties") is not False:
print(path, "additionalProperties is not false")
if props != req:
print(path, "not required:", sorted(props - req),
"extra:", sorted(req - props))
for key, value in node.items():
check(value, path + (key,))
elif isinstance(node, list):
for i, item in enumerate(node):
check(item, path + (i,))
Run it over your schema before you send it. It prints the same kind of path the API does. It catches the 2 most common rules in one pass instead of one per request.
#2. Put every property in required, and use null for optional
This is the second most common cause, and it's the one that feels like a bug. In normal JSON Schema, leaving a key out of required makes it optional. Strict mode doesn't allow that. OpenAI's guide says all fields must be required, and that the model will return a value for each one.
You emulate an optional field with a union that includes null:
"unit": {
"type": ["string", "null"],
"enum": ["F", "C"]
}
Then list unit in required anyway. The model always returns the key. When it has nothing to say, the value is null.
That changes what your code receives, so check the reading side too. Code that tests whether a key exists will now always find it. You need to test for None or null instead. I've seen this cause a quieter bug after the schema error is gone. Nothing crashes, but every optional field reads as present.
If you have 12 optional fields, you'll write 12 nullable types and list all 12 in required. It's verbose, but your code gets a predictable shape back every time.
Library schemas cause this one as well. Pydantic leaves a field with a default out of required. Zod's .optional() does the same. In Zod, reach for .nullable() instead, which keeps the key and allows null. The Extra required key variant is the reverse problem. Your required array names a key that doesn't exist in properties, usually because of a typo or a renamed field.
#3. Don't put anyOf at the root
OpenAI's guide is explicit that the root of the schema must be an object and must not use anyOf. It calls out Zod by name. A discriminated union (one schema that's either shape A or shape B, picked by a tag field) produces an anyOf at the top level, so it gets rejected.
The guide's own examples check for a 400 with the error code invalid_json_schema in this case. I couldn't find the exact message text in the docs, so match on the code rather than the wording.
The fix is to wrap the union. Make the root an object with a single property, say result, and put the anyOf inside it. anyOf is supported below the root, as long as each branch is itself valid under the same subset. That means every branch object still needs its own additionalProperties: false and a complete required list.
#4. Remove the keywords strict mode doesn't support
Strict mode supports String, Number, Boolean, Integer, Object, Array, Enum and anyOf. It doesn't support the composition keywords at all. According to the guide, that's allOf, not, dependentRequired, dependentSchemas, if, then and else. If your schema uses any of them, rewrite that part or move the rule into your own validation code.
The supported constraint list is short. For strings it names pattern and format, with 9 formats including date-time, email and uuid. For numbers it names minimum, maximum, exclusiveMinimum, exclusiveMaximum and multipleOf. For arrays it names minItems and maxItems.
Fine-tuned models are stricter still. The guide lists minLength, maxLength, pattern, format, minimum, maximum, multipleOf, patternProperties, minItems and maxItems as unsupported there. Because minLength and maxLength aren't on the supported list for strings at all, I treat them as unsafe everywhere. I enforce length in code after parsing. That's a few lines, and it never fails at request time.
#5. Check you're inside the size limits
Big generated schemas hit hard limits that hand-written ones rarely reach. These are the numbers in OpenAI's guide as of November 2026:
| Limit | Value |
|---|---|
| Object properties, total | 5,000 |
| Levels of nesting | 10 |
| Total length of property names, definition names, enum and const values | 120,000 characters |
| Enum values across the whole schema | 1,000 |
| One string enum with more than 250 values | 15,000 characters total |
The enum limits are the ones you'll meet in practice. A field listing every product SKU or every country code fills them quickly. If your schema is generated from a database with 40 tables, you can reach the 5,000-property cap sooner than you'd expect. When an enum gets that big, it's usually better as a plain string that you validate against your own list after the response arrives.
#6. Let the SDK build the schema
OpenAI's guide shows the Python and JavaScript SDKs building strict schemas from a Pydantic model or a Zod object. In Python you pass the model to client.responses.parse as text_format. In JavaScript you use zodTextFormat. The helper generates the JSON and parses the reply back into a typed object.
That removes the drift between your types and a hand-written schema, which is where most of these errors start. It doesn't make an unsupported construct valid, though. A root union or an allOf still gets rejected.
A note on naming, because it confuses people. The error says response_format, which is the Chat Completions parameter. The Responses API takes the same schema under text.format. The schema rules in the guide apply to both.
#Which way to build the schema
| Approach | Drift from your types | What you still have to check |
|---|---|---|
| Hand-written JSON | High | Every rule, by hand |
Raw model_json_schema() or a generic Zod converter |
Low | additionalProperties and required on every object |
SDK helper (responses.parse, zodTextFormat) |
Low | Root unions and unsupported keywords |
#Match your symptom to the fix
| You see | Go to |
|---|---|
additionalProperties with a non-empty context |
Section 1, at that path |
required must include every key |
Section 2 |
Extra required key |
Section 2, then look for a typo |
invalid_json_schema and a Zod union |
Section 3 |
| A schema that passes everything above and still fails | Sections 4 and 5 |
#When it still fails
Cut the schema down. Send just the root object with one string property and confirm it works. Then add sections back, a few at a time, until it breaks. With 30 properties, you need about 5 rounds of halving to get down to 1. Bisecting (halving the schema until the bad part is isolated) is tedious, but it finds the node every time, even when the message is vague. Forum threads note that some messages don't say which rule was violated, and this is the way through when that happens.
Check the model, too. OpenAI's guide says json_schema response formats only work on gpt-4o-mini, gpt-4o-2024-08-06 and later snapshots. An older model is a different error, but it's worth ruling out before you rewrite anything.
Finally, don't mistake a slow first call for a fault. The guide says the first request with a new schema has extra latency while the API processes it, and later requests with the same schema don't. If your schema changes every request (because it's rebuilt with a different description or order each time), you pay that cost on every call.
If your schema is accepted but the output still won't parse, that's a separate problem. The invalid JSON guide covers truncation and refusals. If the model is meant to call a function and won't, see why the model ignores your tool.
Frequently asked questions
Why does OpenAI reject a schema that passes a JSON Schema validator?
Because strict mode accepts only a subset of JSON Schema. A schema can be perfectly valid JSON Schema and still break a strict-mode rule, such as a missing additionalProperties: false or an optional key left out of required.
How do I make a field optional in Structured Outputs?
List it in required anyway and give it a union type with null, for example "type": ["string", "null"]. The model always returns the key, and uses null when it has no value.
What does context=() mean in the error?
It's the path to the node that broke the rule. Empty parentheses mean the root. A path like ('properties', 'address') means the address property under the root's properties.
Can I use a Zod discriminated union?
Not at the root, because it produces an anyOf and the root must be a plain object. Wrap it in an object with a single property and put the union inside that property.
Does turning off strict mode make the error go away?
Fixing the schema is the better route. Without strict mode you lose the guarantee that the output matches your schema, which is the reason to use Structured Outputs at all. The rules are few, and the error tells you where to look.
Written by
Vemuri Abhiram
Founder & Editor
Vemuri Abhiram is the founder and editor of Underread, where he writes about AI tools, software, and practical technology. He covers hands-on tool reviews, detailed guides, product comparisons, and emerging technologies.
You might also like
How to Fix “max_tokens: … which is the maximum allowed number of output tokens” in the Anthropic API
Why the Anthropic API rejects your max_tokens with a 400, how to read the 2 numbers in the message, and the fixes in the order they usually apply.
Vemuri Abhiram9 min read
How to Fix “CUDA out of memory” When Running a Local LLM
Why a model that loaded yesterday runs out of VRAM today, and the 5 fixes in the order that costs you the least quality.
Vemuri Abhiram6 min read
How to Fix “The requested webhook is not registered” in n8n (404)
Why an n8n webhook works while you watch it and 404s afterwards, and the 5 causes ranked by how often they're the answer.
Vemuri Abhiram5 min read
More from Underread, once a week.
The guides worth reading and the tests worth trusting. One email, every Friday.
No spam. Unsubscribe in one click.

