fix: preserve free-form OpenAI tool schemas by jan-kubica · Pull Request #933 · TanStack/ai

jan-kubica · 2026-07-14T10:14:09Z

What changed

detect open/free-form object schemas before OpenAI strict normalization
fall back to strict: false while preserving additionalProperties
add converter unit coverage and a final-wire Playwright regression test

Root cause

Strict compatibility checked unsupported keywords and typeless nodes, but not open objects. Strict normalization could therefore close hybrid maps and change their semantics, while property-less maps could reach OpenAI as invalid strict schemas.

Impact

Function tools with record/map inputs keep accepting dynamic keys and no longer fail the entire OpenAI request on strict-schema validation.

Test plan

pnpm test:pr
pnpm --filter @tanstack/ai-e2e test:e2e
focused OpenAI schema/tool converter Vitest suites
OpenAI package typecheck and ESLint

Summary by CodeRabbit

Bug Fixes
- Improved handling of free-form map schemas in OpenAI tool requests.
- Automatically uses non-strict tool formatting when dynamic object keys are required, preventing schema validation errors.
- Preserves dynamic key definitions and supported value types in serialized requests.
Tests
- Added coverage for nested and free-form map schemas.
- Added end-to-end validation of tool serialization for dynamic-key inputs.

coderabbitai · 2026-07-14T10:14:18Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6f6e48df-b0e1-44cf-a18e-71cfa4100482

📥 Commits

Reviewing files that changed from the base of the PR and between 5fcaf90 and 745adbc.

📒 Files selected for processing (6)

.changeset/calm-maps-remain.md
packages/openai-base/src/utils/schema-converter.ts
packages/openai-base/tests/schema-converter.test.ts
packages/openai-base/tests/tool-converter-strict-fallback.test.ts
testing/e2e/src/routes/api.openai-shell-skills-wire.ts
testing/e2e/tests/openai-shell-skills-wire.spec.ts

📝 Walkthrough

Walkthrough

Free-form map schemas are now identified as incompatible with OpenAI strict mode. Tool converters emit strict: false while preserving dynamic-key schemas, with unit and end-to-end coverage for the serialized request.

Changes

Open-object tool fallback

Layer / File(s)	Summary
Open-object compatibility detection `packages/openai-base/src/utils/schema-converter.ts`, `packages/openai-base/tests/schema-converter.test.ts`	`isStrictModeCompatible` rejects open and hybrid object schemas while accepting explicitly closed empty objects.
Non-strict converter fallback `packages/openai-base/tests/tool-converter-strict-fallback.test.ts`	Responses, chat-completions, and function-tool conversions emit `strict: false` for free-form map schemas, preserving response parameters.
End-to-end wire validation `testing/e2e/src/routes/api.openai-shell-skills-wire.ts`, `testing/e2e/tests/openai-shell-skills-wire.spec.ts`, `.changeset/calm-maps-remain.md`	The route sends a free-form map tool, the wire test verifies its serialized schema, and a patch changeset records the update.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Route
  participant OpenAIAdapter
  participant RequestCapture
  Route->>OpenAIAdapter: pass freeFormMapTool
  OpenAIAdapter->>RequestCapture: serialize strict: false
  RequestCapture-->>Route: expose dynamic labels schema

Possibly related PRs

TanStack/ai#786: Extends strict-schema compatibility and fallback handling for OpenAI tool conversion.
TanStack/ai#790: Adds related strict-schema fallback logic and test coverage.
TanStack/ai#833: Updates isStrictModeCompatible for another schema shape requiring non-strict tools.

Suggested reviewers: alemtuzlak

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers the change, root cause, impact, and tests, but it omits the required checklist and release impact sections from the template.	Add the template sections with completed checklist items and state whether this change affects published code or is docs/CI/dev-only.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: preserving free-form OpenAI tool schemas.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

testing/e2e/tests/openai-shell-skills-wire.spec.ts

Parsing error: "parserOptions.project" has been provided for @typescript-eslint/parser.
The file was not found in any of the provided project(s): testing/e2e/tests/openai-shell-skills-wire.spec.ts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

nx-cloud · 2026-07-14T12:39:53Z

View your CI Pipeline Execution ↗ for commit 745adbc

Command	Status	Duration	Result
`nx run-many --targets=build --exclude=examples/...`	✅ Succeeded	14s	View ↗

☁️ Nx Cloud last updated this comment at 2026-07-14 12:39:53 UTC

pkg-pr-new · 2026-07-14T12:40:45Z

Open in StackBlitz

@tanstack/ai

npm i https://pkg.pr.new/@tanstack/ai@933

@tanstack/ai-acp

npm i https://pkg.pr.new/@tanstack/ai-acp@933

@tanstack/ai-angular

npm i https://pkg.pr.new/@tanstack/ai-angular@933

@tanstack/ai-anthropic

npm i https://pkg.pr.new/@tanstack/ai-anthropic@933

@tanstack/ai-bedrock

npm i https://pkg.pr.new/@tanstack/ai-bedrock@933

@tanstack/ai-claude-code

npm i https://pkg.pr.new/@tanstack/ai-claude-code@933

@tanstack/ai-client

npm i https://pkg.pr.new/@tanstack/ai-client@933

@tanstack/ai-code-mode

npm i https://pkg.pr.new/@tanstack/ai-code-mode@933

@tanstack/ai-code-mode-skills

npm i https://pkg.pr.new/@tanstack/ai-code-mode-skills@933

@tanstack/ai-codex

npm i https://pkg.pr.new/@tanstack/ai-codex@933

@tanstack/ai-devtools-core

npm i https://pkg.pr.new/@tanstack/ai-devtools-core@933

@tanstack/ai-elevenlabs

npm i https://pkg.pr.new/@tanstack/ai-elevenlabs@933

@tanstack/ai-event-client

npm i https://pkg.pr.new/@tanstack/ai-event-client@933

@tanstack/ai-fal

npm i https://pkg.pr.new/@tanstack/ai-fal@933

@tanstack/ai-gemini

npm i https://pkg.pr.new/@tanstack/ai-gemini@933

@tanstack/ai-grok

npm i https://pkg.pr.new/@tanstack/ai-grok@933

@tanstack/ai-grok-build

npm i https://pkg.pr.new/@tanstack/ai-grok-build@933

@tanstack/ai-groq

npm i https://pkg.pr.new/@tanstack/ai-groq@933

@tanstack/ai-isolate-cloudflare

npm i https://pkg.pr.new/@tanstack/ai-isolate-cloudflare@933

@tanstack/ai-isolate-node

npm i https://pkg.pr.new/@tanstack/ai-isolate-node@933

@tanstack/ai-isolate-quickjs

npm i https://pkg.pr.new/@tanstack/ai-isolate-quickjs@933

@tanstack/ai-mcp

npm i https://pkg.pr.new/@tanstack/ai-mcp@933

@tanstack/ai-mistral

npm i https://pkg.pr.new/@tanstack/ai-mistral@933

@tanstack/ai-ollama

npm i https://pkg.pr.new/@tanstack/ai-ollama@933

@tanstack/ai-openai

npm i https://pkg.pr.new/@tanstack/ai-openai@933

@tanstack/ai-opencode

npm i https://pkg.pr.new/@tanstack/ai-opencode@933

@tanstack/ai-openrouter

npm i https://pkg.pr.new/@tanstack/ai-openrouter@933

@tanstack/ai-preact

npm i https://pkg.pr.new/@tanstack/ai-preact@933

@tanstack/ai-react

npm i https://pkg.pr.new/@tanstack/ai-react@933

@tanstack/ai-react-ui

npm i https://pkg.pr.new/@tanstack/ai-react-ui@933

@tanstack/ai-sandbox

npm i https://pkg.pr.new/@tanstack/ai-sandbox@933

@tanstack/ai-sandbox-cloudflare

npm i https://pkg.pr.new/@tanstack/ai-sandbox-cloudflare@933

@tanstack/ai-sandbox-daytona

npm i https://pkg.pr.new/@tanstack/ai-sandbox-daytona@933

@tanstack/ai-sandbox-docker

npm i https://pkg.pr.new/@tanstack/ai-sandbox-docker@933

@tanstack/ai-sandbox-local-process

npm i https://pkg.pr.new/@tanstack/ai-sandbox-local-process@933

@tanstack/ai-sandbox-sprites

npm i https://pkg.pr.new/@tanstack/ai-sandbox-sprites@933

@tanstack/ai-sandbox-vercel

npm i https://pkg.pr.new/@tanstack/ai-sandbox-vercel@933

@tanstack/ai-solid

npm i https://pkg.pr.new/@tanstack/ai-solid@933

@tanstack/ai-solid-ui

npm i https://pkg.pr.new/@tanstack/ai-solid-ui@933

@tanstack/ai-svelte

npm i https://pkg.pr.new/@tanstack/ai-svelte@933

@tanstack/ai-utils

npm i https://pkg.pr.new/@tanstack/ai-utils@933

@tanstack/ai-vue

npm i https://pkg.pr.new/@tanstack/ai-vue@933

@tanstack/ai-vue-ui

npm i https://pkg.pr.new/@tanstack/ai-vue-ui@933

@tanstack/openai-base

npm i https://pkg.pr.new/@tanstack/openai-base@933

@tanstack/preact-ai-devtools

npm i https://pkg.pr.new/@tanstack/preact-ai-devtools@933

@tanstack/react-ai-devtools

npm i https://pkg.pr.new/@tanstack/react-ai-devtools@933

@tanstack/solid-ai-devtools

npm i https://pkg.pr.new/@tanstack/solid-ai-devtools@933

commit: 745adbc

…ict-schema 400 Linear's save_diff_comment.anchor started shipping as a free-form map (propertyNames + open additionalProperties). @tanstack/ai-openai@0.15.2 forced strict:true on every tool and 400d the whole turn on such schemas. @tanstack/openai-base@0.9.8 (PR TanStack/ai#933, shipped in @tanstack/ai-openai@0.17.0) detects free-form-map schemas and emits those tools with strict:false instead, so they stay callable. Bump to pick that up: @tanstack/ai ^0.32.0 -> ^0.42.0 @tanstack/ai-openai ^0.15.2 -> ^0.17.1 @tanstack/ai-mcp ^0.1.3 -> ^0.2.5 zod ^3 -> ^4 (peer of ai-openai 0.17) No runtime code change — the fix lives in the upgraded adapter.

…ict-schema 400 (#6088) ## Problem The deployed Slack triage bot (`examples/slack`) started failing **every** turn with: ``` 400 Invalid schema for function 'save_diff_comment': In context=('properties','anchor'), 'propertyNames' is not permitted. ``` No change on our side triggered it — Linear's hosted MCP server changed the `save_diff_comment` tool schema. Its `anchor` param is now a free-form map (open object declared with `propertyNames` + open `additionalProperties`). The bot fetches Linear's tool list at runtime, so it picked up the new schema automatically. ## Root cause `@tanstack/ai-openai@0.15.2` (what the bot resolves to) forces `strict: true` on every function tool. OpenAI's strict function-calling validator only accepts a subset of JSON Schema and **rejects the entire request (400, before the model runs)** for a free-form-map object like `anchor`. One over-rich third-party tool takes down the whole turn. ## Fix — adopt the upstream fix via a dependency upgrade Already fixed upstream: `@tanstack/openai-base@0.9.8` ([TanStack/ai#933](TanStack/ai#933)) makes the tool converter detect free-form-map schemas and emit those tools with `strict: false` (so they stay callable) instead of forcing an invalid strict schema. First ships in `@tanstack/ai-openai@0.17.0`. The bot's `^0.15.2` range can't reach it, so this bumps the aligned set and refreshes `pnpm-lock.yaml`: | package | before | after | |---|---|---| | `@tanstack/ai` | `^0.32.0` | `^0.42.0` | | `@tanstack/ai-openai` | `^0.15.2` | `^0.17.1` (→ `openai-base@0.9.9`) | | `@tanstack/ai-mcp` | `^0.1.3` | `^0.2.5` | **zod stays at `^3.25.76`.** The repo pins zod to 3.x via a root `pnpm.overrides` (`zod: ">=3.22.3"`), so the whole workspace resolves zod 3 regardless. `ai-openai@0.17` peers `zod ^4` (unmet → advisory warning only), but the strict-schema fix operates on plain JSON Schema, not zod, so it's unaffected. **No runtime code change** — the fix lives entirely in the upgraded adapter (an earlier revision of this PR hand-rolled a schema sanitizer; that's removed in favor of leaning on TanStack's built-in handling). ## Verification ⚠️ Not verifiable in this worktree (example deps aren't installed here). Before merge, in an installed env: - `pnpm --filter slack-example check-types` and `pnpm --filter slack-example test` - One live turn hitting Linear (previously-failing `save_diff_comment` path) - Sanity-check the bot runs on the workspace's pinned **zod 3** despite `ai-openai@0.17`'s `zod ^4` peer (the fix path is zod-independent, but confirm no other `@tanstack/ai` code the bot exercises needs a zod-4-only API). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

fix: preserve free-form OpenAI tool schemas

745adbc

jan-kubica marked this pull request as ready for review July 14, 2026 10:24

jan-kubica mentioned this pull request Jul 14, 2026

fix: enforce AI provider request contracts stella/stella#1158

Merged

AlemTuzlak approved these changes Jul 14, 2026

View reviewed changes

tombeckenham merged commit fbfd4be into TanStack:main Jul 16, 2026
10 checks passed

coderabbitai Bot mentioned this pull request Jul 16, 2026

fix: undo strict null widening for tool inputs #939

Open

4 tasks

github-actions Bot mentioned this pull request Jul 10, 2026

ci: Version Packages #913

Merged

This was referenced Jul 21, 2026

ai-openai: strict-mode tool schemas 400 when a tool declares keywords OpenAI forbids (e.g. propertyNames, free-form objects) #976

Closed

fix(examples): upgrade slack bot's TanStack AI deps to fix OpenAI strict-schema 400 CopilotKit/CopilotKit#6088

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: preserve free-form OpenAI tool schemas - #933

fix: preserve free-form OpenAI tool schemas#933
tombeckenham merged 1 commit into
TanStack:mainfrom
jan-kubica:fix/openai-strict-open-object-schemas

jan-kubica commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Jul 14, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

jan-kubica commented Jul 14, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Root cause

Impact

Test plan

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

nx-cloud Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pkg-pr-new Bot commented Jul 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jan-kubica commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

nx-cloud Bot commented Jul 14, 2026 •

edited

Loading