feat: standard (json) schema compliance #165

AlemTuzlak · 2025-12-20T14:00:36Z

🎯 Changes

Standard schema compliance PR

✅ Checklist

I have followed the steps in the Contributing guide.
I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

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

Summary by CodeRabbit

Release Notes

New Features
- Added Standard Schema / Standard JSON Schema support for flexible schema validation, enabling compatibility with multiple schema libraries (Zod v4+, ArkType, Valibot) and plain JSON Schema across TanStack AI packages.
Chores
- Updated dependencies and minor version bumps across packages.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2025-12-20T14:00:47Z

Walkthrough

This PR migrates TanStack AI from Zod-specific schema handling to Standard JSON Schema support. It introduces a new schema-converter module with type guards and validation utilities, replaces Zod types (z.ZodType, z.infer) with Standard Schema types (SchemaInput, InferSchemaType) across core interfaces, removes the zod-converter module, and updates dependencies to use zod ^4.2.0 with the new @standard-schema/spec package.

Changes

Cohort / File(s)	Summary
Dependency Updates `.changeset/honest-bugs-tell.md`, `examples/ts-*/package.json`, `packages/typescript/ai-client/package.json`, `packages/typescript/smoke-tests/adapters/package.json`, `testing/panel/package.json`	Minor version bumps across TanStack AI packages. Zod upgraded from ^4.1.13 to ^4.2.0 in dev/runtime dependencies. Adds changeset documenting Standard Schema support.
Core Dependencies `packages/typescript/ai/package.json`	Removes peerDependencies block (`@alcyone-labs/zod-to-json-schema`, zod). Adds `@standard-schema/spec` ^1.1.0 as devDependency. Updates zod to ^4.2.0 in devDependencies.
Package.json Removals `packages/typescript/ai-react/package.json`, `packages/typescript/ai-svelte/package.json`, `packages/typescript/ai-solid/package.json`, `packages/typescript/ai-vue/package.json`	Removes zod from devDependencies or transitive dependencies.
Type System Migration `packages/typescript/ai/src/types.ts`	Replaces z.ZodType with StandardJSONSchemaV1 in SchemaInput union. Updates InferSchemaType to derive from StandardJSONSchemaV1 instead of z.infer. Broadens JSONSchema properties (enum, const, default, examples) from any to unknown. Updates Tool generic defaults and documentation.
Tool Definition Updates `packages/typescript/ai/src/activities/chat/tools/tool-definition.ts`	Replaces Zod generics with SchemaInput across ServerTool, ClientTool, ToolDefinitionInstance. Updates InferToolInput and InferToolOutput to use StandardJSONSchemaV1. Changes metadata type from Record<string, any> to Record<string, unknown>. Expands documentation for Standard JSON Schema library support.
Chat Activity Refactor `packages/typescript/ai/src/activities/chat/index.ts`	Replaces z.ZodType with SchemaInput in type parameters. Swaps convertZodToJsonSchema for convertSchemaToJsonSchema. Implements validation using parseWithStandardSchema instead of Zod safeParse. Updates runAgenticStructuredOutput to return InferSchemaType.
Schema Converter Utilities `packages/typescript/ai/src/activities/chat/tools/schema-converter.ts`	New module providing type guards (isStandardJSONSchema, isStandardSchema), validation helpers (validateWithStandardSchema, parseWithStandardSchema), and conversion (convertSchemaToJsonSchema). Includes internal helper makeStructuredOutputCompatible for OpenAI structured output adaptation.
Tool Calls Validation `packages/typescript/ai/src/activities/chat/tools/tool-calls.ts`	Replaces isZodSchema and Zod.parse with isStandardSchema and parseWithStandardSchema. Updates error handling for unknown validation errors. Removes Zod-specific code paths for both streaming and non-streaming tool execution.
Removed Zod Converter `packages/typescript/ai/src/activities/chat/tools/zod-converter.ts`	Removes entire module containing Zod-to-JSON Schema conversion and structured output transformation logic.
Export Updates `packages/typescript/ai/src/index.ts`	Replaces export of convertZodToJsonSchema with convertSchemaToJsonSchema. Adds comment documenting Standard JSON Schema usage.
Adapter Updates `packages/typescript/ai-anthropic/src/tools/custom-tool.ts`, `packages/typescript/ai-ollama/src/adapters/text.ts`	Updates customTool signature to use SchemaInput instead of z.ZodType. Adds type assertion for Ollama tool parameters to ensure JSON Schema compatibility.
Test Updates `packages/typescript/ai/tests/standard-converter.test.ts`	Migrates from convertZodToJsonSchema to convertSchemaToJsonSchema. Adds test coverage for new type guards (isStandardJSONSchema, isStandardSchema) and validation utilities.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

schema-converter.ts: New module with multiple type guards and validation utilities; review logic for StandardJSONSchemaV1 detection, validation result mapping, and structured output transformation
Type system changes (types.ts, tool-definition.ts): Widespread generic parameter updates; verify StandardJSONSchemaV1 inference logic replaces z.infer correctly
Validation refactoring (tool-calls.ts, chat/index.ts): Critical changes to error handling and schema validation paths; ensure parseWithStandardSchema behavior matches previous Zod safeParse semantics
Removed zod-converter.ts: Verify all logic (structured output transformation) is properly replicated in schema-converter.ts
Cross-package consistency: Ensure all dependent packages (ai-anthropic, ai-ollama) align with new SchemaInput types

Poem

🐰 From Zod's strict path to schemas free,
Standard JSON Schema's the key,
Type guards and converters dance with grace,
Validation runs at every place,
TanStack AI finds broader space! 🎉

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: standard (json) schema compliance' clearly and specifically describes the main change: adding Standard Schema and JSON Schema compliance to the TanStack AI packages.
Description check	✅ Passed	The description includes a brief summary, completes all checklist items (contributing guide followed, local testing done, changeset generated), and follows the required template structure with proper sections.
Docstring Coverage	✅ Passed	Docstring coverage is 91.67% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch feat/standard-schema-compliant

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 and usage tips.}

nx-cloud · 2025-12-20T14:04:25Z

View your CI Pipeline Execution ↗ for commit 6840646

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

☁️ Nx Cloud last updated this comment at 2025-12-20 14:07:57 UTC

pkg-pr-new · 2025-12-20T14:06:13Z

Open in StackBlitz

@tanstack/ai

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

@tanstack/ai-anthropic

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

@tanstack/ai-client

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

@tanstack/ai-devtools-core

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

@tanstack/ai-gemini

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

@tanstack/ai-ollama

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

@tanstack/ai-openai

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

@tanstack/ai-react

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

@tanstack/ai-react-ui

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

@tanstack/ai-solid

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

@tanstack/ai-solid-ui

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

@tanstack/ai-svelte

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

@tanstack/ai-vue

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

@tanstack/ai-vue-ui

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

@tanstack/react-ai-devtools

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

@tanstack/solid-ai-devtools

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

commit: 6840646

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (3)

packages/typescript/ai/src/activities/chat/tools/schema-converter.ts (2)
34-47: Minor redundancy in null checks.

Line 40 has a redundant schema !== null check since schema !== null was already verified on line 37. The check on line 41 for schema['~standard'] !== null is the correct one.
🔎 Proposed fix to remove redundant check
 export function isStandardSchema(schema: unknown): schema is StandardSchemaV1 {
   return (
     typeof schema === 'object' &&
     schema !== null &&
     '~standard' in schema &&
     typeof schema['~standard'] === 'object' &&
-    schema !== null &&
     schema['~standard'] !== null &&
     'version' in schema['~standard'] &&
     schema['~standard'].version === 1 &&
     'validate' in schema['~standard'] &&
     typeof schema['~standard'].validate === 'function'
   )
 }
60-122: Consider handling additional schema constructs for structured output compatibility.

The function correctly handles basic object and array types, but doesn't process complex schema constructs like anyOf, oneOf, or allOf that may contain nested objects. If these constructs are used with forStructuredOutput: true, their nested schemas won't be transformed.

This may be acceptable if such complex schemas aren't commonly used with OpenAI structured output, but worth noting for future enhancement.
packages/typescript/ai/src/activities/chat/index.ts (1)
1108-1114: Consider using async validation for robustness.

parseWithStandardSchema throws if the schema only supports async validation. Since runAgenticStructuredOutput is already an async function, using validateWithStandardSchema would handle both sync and async schemas gracefully.
🔎 Proposed fix to use async validation
   // Validate the result against the schema if it's a Standard Schema
   if (isStandardSchema(outputSchema)) {
-    return parseWithStandardSchema<InferSchemaType<TSchema>>(
+    const validationResult = await validateWithStandardSchema<InferSchemaType<TSchema>>(
       outputSchema,
       result.data,
     )
+    if (!validationResult.success) {
+      const errorMessages = validationResult.issues
+        .map((issue) => issue.message)
+        .join(', ')
+      throw new Error(`Validation failed: ${errorMessages}`)
+    }
+    return validationResult.data
   }
This would also require adding validateWithStandardSchema to the imports on line 14.

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 254b248 and 6840646.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (23)

.changeset/honest-bugs-tell.md (1 hunks)
examples/ts-react-chat/package.json (1 hunks)
examples/ts-solid-chat/package.json (1 hunks)
examples/ts-svelte-chat/package.json (1 hunks)
examples/ts-vue-chat/package.json (1 hunks)
packages/typescript/ai-anthropic/src/tools/custom-tool.ts (2 hunks)
packages/typescript/ai-client/package.json (1 hunks)
packages/typescript/ai-ollama/src/adapters/text.ts (1 hunks)
packages/typescript/ai-react/package.json (1 hunks)
packages/typescript/ai-solid/package.json (1 hunks)
packages/typescript/ai-svelte/package.json (1 hunks)
packages/typescript/ai-vue/package.json (1 hunks)
packages/typescript/ai/package.json (1 hunks)
packages/typescript/ai/src/activities/chat/index.ts (13 hunks)
packages/typescript/ai/src/activities/chat/tools/schema-converter.ts (1 hunks)
packages/typescript/ai/src/activities/chat/tools/tool-calls.ts (9 hunks)
packages/typescript/ai/src/activities/chat/tools/tool-definition.ts (8 hunks)
packages/typescript/ai/src/activities/chat/tools/zod-converter.ts (0 hunks)
packages/typescript/ai/src/index.ts (1 hunks)
packages/typescript/ai/src/types.ts (7 hunks)
packages/typescript/ai/tests/standard-converter.test.ts (33 hunks)
packages/typescript/smoke-tests/adapters/package.json (1 hunks)
testing/panel/package.json (1 hunks)

💤 Files with no reviewable changes (1)

packages/typescript/ai/src/activities/chat/tools/zod-converter.ts

🧰 Additional context used

📓 Path-based instructions (6)

examples/**

📄 CodeRabbit inference engine (CLAUDE.md)

Examples are not built by Nx and should be run independently from their directories with pnpm dev or pnpm install && pnpm dev

Files:

examples/ts-solid-chat/package.json
examples/ts-vue-chat/package.json
examples/ts-svelte-chat/package.json
examples/ts-react-chat/package.json

**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: Use tree-shakeable adapter architecture for provider implementations - export specialized adapters (text, embedding, summarize, image) as separate imports from /adapters subpath rather than monolithic adapters
Use Zod for runtime schema validation and type inference, particularly for tool input/output definitions with toolDefinition() and Zod schema inference
Implement isomorphic tool system using toolDefinition() with .server() and .client() implementations for dual-environment execution
Use type-safe per-model configuration with provider options typed based on selected model to ensure compile-time safety
Implement stream processing with StreamProcessor for handling chunked responses and support partial JSON parsing for streaming AI responses

Files:

packages/typescript/ai-anthropic/src/tools/custom-tool.ts
packages/typescript/ai/src/index.ts
packages/typescript/ai-ollama/src/adapters/text.ts
packages/typescript/ai/tests/standard-converter.test.ts
packages/typescript/ai/src/activities/chat/tools/schema-converter.ts
packages/typescript/ai/src/activities/chat/tools/tool-definition.ts
packages/typescript/ai/src/activities/chat/index.ts
packages/typescript/ai/src/types.ts
packages/typescript/ai/src/activities/chat/tools/tool-calls.ts

**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (CLAUDE.md)

Use camelCase for function and variable names throughout the codebase

Files:

packages/typescript/ai-anthropic/src/tools/custom-tool.ts
packages/typescript/ai/src/index.ts
packages/typescript/ai-ollama/src/adapters/text.ts
packages/typescript/ai/tests/standard-converter.test.ts
packages/typescript/ai/src/activities/chat/tools/schema-converter.ts
packages/typescript/ai/src/activities/chat/tools/tool-definition.ts
packages/typescript/ai/src/activities/chat/index.ts
packages/typescript/ai/src/types.ts
packages/typescript/ai/src/activities/chat/tools/tool-calls.ts

packages/typescript/*/src/index.ts

📄 CodeRabbit inference engine (CLAUDE.md)

Export tree-shakeable adapters with clear subpath exports in package.json (e.g., @tanstack/ai/adapters, @tanstack/ai-openai/adapters) to minimize bundle size

Files:

packages/typescript/ai/src/index.ts

packages/typescript/*/src/adapters/*.ts

📄 CodeRabbit inference engine (CLAUDE.md)

Create individual adapter implementations for each provider capability (text, embed, summarize, image) with separate exports to enable tree-shaking

Files:

packages/typescript/ai-ollama/src/adapters/text.ts

**/*.test.ts

📄 CodeRabbit inference engine (CLAUDE.md)

Write unit tests using Vitest alongside source files with .test.ts naming convention

Files:

packages/typescript/ai/tests/standard-converter.test.ts

🧠 Learnings (12)

📓 Common learnings

Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.{ts,tsx} : Use Zod for runtime schema validation and type inference, particularly for tool input/output definitions with `toolDefinition()` and Zod schema inference