Skip to content
Source
Sign inSign up
TanStack/ai

`@tanstack/openai-base`: OpenAI-compatible adapters always send tool schemas in strict mode, so optional fields become required #2114

Send to my agent
Openmrfratello(GitHub profile, opens in a new tab) opened this issue 0 comments

TanStack 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: false is injected everywhere,
  • strict: true is 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-openrouter by sending strict: false with 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: mapOptionsToRequest is protected and calls convertToolsToChatCompletionsFormat directly; there is no convertTools hook on the Chat Completions adapter. Our current workaround is patching mapOptionsToRequest on the adapter instance.
  • Tangential but related: Zod schemas using .trim().pipe(...) (i.e. z.string().trim().pipe(z.string().min(3))) lose minLength in 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.

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.
  1. tanstack-source added labelsbug

  2. github-actions[bot](GitHub profile, opens in a new tab) added labelswaiting-on: maintainer

Sign in to join this conversation.