`@tanstack/openai-base`: OpenAI-compatible adapters always send tool schemas in strict mode, so optional fields become required #2114
Send to my agentTanStack AI version#
1.0.0
Framework/Library version#
react
Describe the bug and the steps to reproduce it#
TanStack AI version#
@tanstack/ai@1.0.0, @tanstack/ai-openai@1.0.0, @tanstack/openai-base@1.0.0.
Also reproduced on the latest published builds (@tanstack/ai@1.2.0,
@tanstack/openai-base@1.0.2), and the relevant code is still hardcoded on
main (packages/openai-base/src/tools/function-tool.ts).
Runtime + Framework/Library version#
Node 24, Zod 4.6.7, openaiCompatible({ api: 'chat-completions' }) pointed at
a non-OpenAI provider. No React involved — this is a server-side
tool-definition issue.
Describe the bug#
When a tool's inputSchema has no required fields, the Chat Completions /
Responses adapters in @tanstack/openai-base rewrite it to OpenAI strict
mode unconditionally:
- every property name is pushed into
required, "type": "string"becomes"type": ["string", "null"],additionalProperties: falseis injected everywhere,strict: trueis set on the tool.
@tanstack/ai itself produces a correct schema (~standard.jsonSchema.input({ target: 'draft-07' }) → no required at all), so the corruption happens purely
inside the adapter conversion. There is no option to opt out — only
strictFallbackWarning exists.
For OpenAI-compatible providers serving non-OpenAI models, the model sees the tool definition as "every argument is mandatory". In our case a users-search tool has ~10 optional filters and the LLM insists on filling all of them, producing nonsense queries. It cannot simply omit them: strict mode declares them required.
This is the same class of bug that was fixed for the OpenRouter adapter in
#1542 / #1545. Chat Completions is non-strict by default per OpenAI's own
docs (strict must be explicitly opted into), so object properties are allowed
to be omitted. The adapter should preserve the schema as authored, or at least
allow opting out.
Minimal repro (also in the sandbox below):
import { z } from 'zod';
import { convertToolsToChatCompletionsFormat } from '@tanstack/openai-base';
const inputSchema = z.object({
page: z.number().default(1),
filters: z
.object({
firstName: z.string().optional(),
role: z.string().optional(),
})
.optional(),
});
const { $schema, ...jsonSchema } = z.toJSONSchema(inputSchema, {
io: 'input',
target: 'draft-07',
});
// jsonSchema.required === undefined ✅
const tools = convertToolsToChatCompletionsFormat([
{ name: 'getUsers', description: 'Get users', inputSchema: jsonSchema },
]);
Actual output:
{
"type": "function",
"function": {
"name": "getUsers",
"parameters": {
"type": "object",
"properties": {
"page": { "default": 1, "type": ["number", "null"] },
"filters": {
"type": ["object", "null"],
"properties": {
"firstName": { "type": ["string", "null"] },
"role": { "type": ["string", "null"] }
},
"required": ["firstName", "role"],
"additionalProperties": false
}
},
"required": ["page", "filters"],
"additionalProperties": false
},
"strict": true
}
}
Your Minimal, Reproducible Example#
CodeSandbox (plain Node, no build step, npm start):
https://codesandbox.io/s/8rypt3
It prints the schema produced by @tanstack/ai, the payload emitted by
@tanstack/openai-base, and asserts that optional fields stay optional. It
currently prints:
FAIL: optional tool fields were turned into required ones:
- strict is true, expected false
- top-level required is ["page","filters"], expected []
- filters.required is ["firstName","role"], expected []
- page.type was widened to ["number", "null"]
- filters.type was widened to ["object", "null"]
The self-contained script is also included inline above, in case the sandbox is unavailable.
Expected behavior#
The adapter should not upgrade strict on its own, or should expose a way to
disable it. Either:
openaiCompatible({ /* ... */, strictTools: false })
or a per-tool flag in toolDefinition, would be enough. With strict: false,
parameters should be exactly the JSON Schema @tanstack/ai produced — no
required injection, no null widening, no additionalProperties.
Screenshots or video#
N/A — console output above is the evidence.
Desktop#
N/A (server-side).
Additional context#
- Precedent: #1545 fixed exactly this for
ai-openrouterby sendingstrict: falsewith the schema as authored (and stripping strict-synthesized nulls in the Responses path). - Validation is not the problem:
createToolInputNormalizer/undoNullWidening(#939) already removes the injected nulls before parsing, so execution works. The damage is prompt-level: the model is told these arguments are required. - The conversion is not overridable from outside:
mapOptionsToRequestisprotectedand callsconvertToolsToChatCompletionsFormatdirectly; there is noconvertToolshook on the Chat Completions adapter. Our current workaround is patchingmapOptionsToRequeston the adapter instance. - Tangential but related: Zod schemas using
.trim().pipe(...)(i.e.z.string().trim().pipe(z.string().min(3))) loseminLengthin input-mode JSON Schema — only{ "type": "string" }survives. Separate issue, mentioning it because it affects the same tool definitions.
PR intent: Yes, I think I know how to fix it and will discuss it in the comments of this issue.
Your Minimal, Reproducible Example - (Sandbox Highly Recommended)#
https://codesandbox.io/s/8rypt3
Screenshots or Videos (Optional)#
No response
Do you intend to try to help solve this bug with your own PR?#
None
Terms & Code of Conduct#
- I agree to follow this project's Code of Conduct
- I understand that if my bug cannot be reliable reproduced in a debuggable environment, it will probably not be fixed and this issue may even be closed.
tanstack-source added labelsbug
github-actions[bot](GitHub profile, opens in a new tab) assignedjherr
github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer
Sign in to join this conversation.