fix(ai): preserve tuple item schemas in structured output conversion

[AlemTuzlak]

convertSchemaForStructuredOutput kept only items[0] for draft-07 tuples, so later positions were dropped. This PR maps every tuple position. Homogeneous arrays still use one widening map, so undoNullWidening applies it to every element (jsve’s note on #1210).

Changes

• Keep every positional schema in a tuple items array, including tuples nested in object properties.
• Keep a single items map for homogeneous arrays. A list-shaped map would un-widen only index 0.
• Docs: no new public API. Structured-output conversion now matches JSON Schema for tuple items.
• Changeset: .changeset/ai-tuple-item-maps.md for @tanstack/ai.

Follow-up to #1210, which fixed the same tuple drop in @tanstack/openai-base.

Checklist

• I have followed the steps in the Contributing guide.
• I have tested code changes locally with pnpm run test:pr, or these tests do not apply to this pull request.
• I fully understand the code in this pull request, including any code generated with AI assistance.
• Docs: I updated docs/ for this change, or this change is not user-facing.
• Changeset: I added a changeset (pnpm changeset), or this PR does not change a published package.

Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Root cause

Issue. A structured-output schema with a bbox tuple (items: [{ minimum: -180 }, …]) kept only the first position.

Cause. Both array branches in makeStructuredOutputCompatible used Array.isArray(items) ? items[0] : items.

Fix. Map every tuple entry. Store a list of maps for tuples and one map for a homogeneous items schema.

Possible alternatives

• Fold this into fix(openai-base): keep tuple items arrays during strict conversion #1210. That PR is openai-base only. This converter is @tanstack/ai.
• Always store a list of maps. That is jsve’s bug: a homogeneous array would un-widen only index 0.

Testing

Commands run

1. pnpm --filter @tanstack/ai... build — passed
2. pnpm --filter @tanstack/ai exec vitest run tests/tuple-array-null-widening.test.ts tests/chat-structured-output-null-normalization.test.ts — 12 passed
3. pnpm --filter @tanstack/ai test:types — passed
4. pnpm --filter @tanstack/ai test:oxlint — passed (existing any warnings only)
5. pnpm test:pr — not run
6. E2E — not run. Coverage is unit tests on the converter.

Manual test

1. On main, pass { type: 'object', properties: { bbox: { type: 'array', items: [{ type: 'number', minimum: -180 }, { type: 'number', minimum: -90 }] } }, required: ['bbox'] } to convertSchemaForStructuredOutput. items becomes the first number schema only.
2. On this branch, items stays a two-entry array.

Gate 1 on main:

FAIL: items is not an array {"type":"number","minimum":-180}

On this branch:

PASS: tuple items stayed an array

How this PR makes testing easy. packages/ai/tests/tuple-array-null-widening.test.ts covers tuples and jsve’s 3-element homogeneous round trip.

Linked issues

Related: #1210, #1208

Risk / rollback

Low. Tuple structured-output schemas keep every position. Homogeneous arrays keep the old single-map behavior. Revert the PR to undo.

Summary by CodeRabbit

• Bug Fixes

  • Fixed structured outputs so tuple-based array schemas preserve every positional definition.
  • Corrected handling of optional tuple elements and homogeneous arrays when removing widened null values.

• Tests

  • Added coverage for tuple schema preservation and null handling across array elements.

• Chores

  • Documented a patch release for the AI package.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 80649f00-55d1-4e7d-9755-f192300b684c

📥 Commits

Reviewing files that changed from the base of the PR and between a7e0798 and 1d5ef16.

📒 Files selected for processing (3)

• .changeset/ai-tuple-item-maps.md
• packages/ai/src/activities/chat/tools/schema-converter.ts
• packages/ai/tests/tuple-array-null-widening.test.ts

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

The schema converter now preserves draft-07 tuple item schemas and records positional null-widening maps. Homogeneous arrays retain one shared map for all elements. Tests cover tuple preservation, optional tuple objects, and homogeneous-array null restoration.

Changes

Tuple Array Conversion

Layer / File(s)	Summary
Array schema conversion packages/ai/src/activities/chat/tools/schema-converter.ts	coerceArrayItems preserves tuple positions and records positional or shared null-widening maps in both array conversion paths.
Array conversion validation packages/ai/tests/tuple-array-null-widening.test.ts, .changeset/ai-tuple-item-maps.md	Tests cover tuple schemas, optional tuple objects, and homogeneous arrays. The changeset documents the patch release. ते

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 1d5ef

This preserves all positional tuple schemas without changing homogeneous-array behavior or adding new runtime surfaces. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the primary change: preserving tuple item schemas during structured-output conversion.
Description check	✅ Passed	The description follows the required template and includes the change summary, checklist, release impact, testing results, root cause, alternatives, linked issues, and rollback risk. It clearly states…
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.

Full details: Description check

Explanation

The description follows the required template and includes the change summary, checklist, release impact, testing results, root cause, alternatives, linked issues, and rollback risk. It clearly states that pnpm test:pr and E2E tests were not run.

Full details: Docstring Coverage

Explanation

Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 2 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/ai-tuple-item-maps

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 0a70023

Command	Status	Duration	Result
nx affected --targets=test:sherif,test:knip,tes...	✅ Succeeded	8m 24s	View ↗
nx run-many --targets=build --exclude=examples/...	✅ Succeeded	2s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-08-27 21:58:12 UTC

[pkg-pr-new]

Open in StackBlitz

@tanstack/ai

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

@tanstack/ai-acp

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

@tanstack/ai-angular

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

@tanstack/ai-anthropic

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

@tanstack/ai-bedrock

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

@tanstack/ai-byteplus

npm i https://pkg.pr.new/@tanstack/ai-byteplus@1257

@tanstack/ai-claude-code

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

@tanstack/ai-client

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

@tanstack/ai-code-mode

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

@tanstack/ai-code-mode-snippets

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

@tanstack/ai-codex

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

@tanstack/ai-cohere

npm i https://pkg.pr.new/@tanstack/ai-cohere@1257

@tanstack/ai-devtools-core

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

@tanstack/ai-durable-stream

npm i https://pkg.pr.new/@tanstack/ai-durable-stream@1257

@tanstack/ai-elevenlabs

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

@tanstack/ai-event-client

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

@tanstack/ai-fal

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

@tanstack/ai-gemini

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

@tanstack/ai-grok

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

@tanstack/ai-grok-build

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

@tanstack/ai-groq

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

@tanstack/ai-isolate-cloudflare

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

@tanstack/ai-isolate-daytona

npm i https://pkg.pr.new/@tanstack/ai-isolate-daytona@1257

@tanstack/ai-isolate-node

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

@tanstack/ai-isolate-quickjs

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

@tanstack/ai-isolate-quickjs-bun

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

@tanstack/ai-llmgateway

npm i https://pkg.pr.new/@tanstack/ai-llmgateway@1257

@tanstack/ai-lovable

npm i https://pkg.pr.new/@tanstack/ai-lovable@1257

@tanstack/ai-mcp

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

@tanstack/ai-memory

npm i https://pkg.pr.new/@tanstack/ai-memory@1257

@tanstack/ai-mistral

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

@tanstack/ai-octane

npm i https://pkg.pr.new/@tanstack/ai-octane@1257

@tanstack/ai-ollama

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

@tanstack/ai-openai

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

@tanstack/ai-opencode

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

@tanstack/ai-openrouter

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

@tanstack/ai-perplexity

npm i https://pkg.pr.new/@tanstack/ai-perplexity@1257

@tanstack/ai-persistence

npm i https://pkg.pr.new/@tanstack/ai-persistence@1257

@tanstack/ai-preact

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

@tanstack/ai-react

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

@tanstack/ai-react-ui

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

@tanstack/ai-sandbox

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

@tanstack/ai-sandbox-cloudflare

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

@tanstack/ai-sandbox-daytona

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

@tanstack/ai-sandbox-docker

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

@tanstack/ai-sandbox-local-process

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

@tanstack/ai-sandbox-sprites

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

@tanstack/ai-sandbox-upstash-box

npm i https://pkg.pr.new/@tanstack/ai-sandbox-upstash-box@1257

@tanstack/ai-sandbox-vercel

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

@tanstack/ai-skills

npm i https://pkg.pr.new/@tanstack/ai-skills@1257

@tanstack/ai-solid

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

@tanstack/ai-solid-ui

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

@tanstack/ai-svelte

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

@tanstack/ai-utils

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

@tanstack/ai-vercel-gateway

npm i https://pkg.pr.new/@tanstack/ai-vercel-gateway@1257

@tanstack/ai-vertex

npm i https://pkg.pr.new/@tanstack/ai-vertex@1257

@tanstack/ai-vue

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

@tanstack/ai-vue-ui

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

@tanstack/openai-base

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

@tanstack/preact-ai-devtools

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

@tanstack/react-ai-devtools

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

@tanstack/solid-ai-devtools

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

@tanstack/svelte-ai-devtools

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

commit: 0a70023