# What changed in @mastra/schema-compat

> 46 changes in @mastra/schema-compat 1 from its official release notes, upgrade guides and advisories: 2 breaking, 1 new APIs and options. Each one cited. Sources checked 2026-10-20. HTML: https://unstale.sh/npm/@mastra/schema-compat/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @mastra/schema-compat 1

### Breaking changes

- Tool execute functions now receive the transformed output type for Standard Schemas instead of a union of input and output types. (1.3.14) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1314)
- Optional fields inside nullable or nullish objects or arrays returned as null are now dropped, matching behavior for non-nullable parents. (1.3.12) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1312)

### New APIs and options

- Set this option to `true` to keep strict mode for structured output schemas with free-form keys. (1.3.15) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1315)

### Performance

- Reduced TypeScript memory usage for applications that define many tools with Zod schemas. (1.3.10) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1310)

### Behavior and default changes

- Tool requestContextSchema accepts Standard Schemas that transform their input, and tool request context is typed with the transformed output. (1.3.14) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1314)
- Meta and DeepSeek schemas now move numeric constraints into the field description instead of sending raw number bounds or minimum/maximum keywords to the model. (1.3.4) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#134)

### Fixes and other changes

- Optional tool inputs are left empty instead of being filled with made-up values when the Azure deployment name contains an OpenAI model name. (1.3.15) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1315)
- OpenAI models can leave optional tool inputs empty when those inputs accept more than one type, rather than filling them with made-up values. (1.3.15) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1315)
- Structured output with free-form keys, such as `z.record(z.string(), z.string())`, now works on OpenAI; these schemas are sent without strict mode. (1.3.15) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1315)
- OpenAI strict-mode schema preparation no longer rejects allOf object schemas with properties named constructor, toString, or __proto__. (1.3.13) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1313)
- Tools with optional number parameters that have a format now return responses as expected instead of failing silently. (1.3.12) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1312)
- Nullable Zod v4 enums and literals now include null among exported allowed values, so tool parameters, OpenAPI schemas and dataset schemas match the Zod schema. (1.3.12) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1312)
- Claude on Vertex now uses the Anthropic compatibility layer, preserving nullable parameters as JSON Schema `type: ['string', 'null']`; Gemini on Vertex is unchanged. (1.3.11) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1311)
- JSON Schema adapter declarations use bundled Ajv types, so consumers no longer need a separate Ajv installation. (1.3.11) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1311)
- Fixed loading from CommonJS, which previously failed with “jsonSchemaToZod is not a function.” (1.3.11) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1311)
- Generated schemas use `z.record(z.string(), value)` so schemas with `additionalProperties` or `patternProperties` validate correctly on the noted Zod versions. (1.3.11) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1311)
- Recursively removes validation keywords rejected by OpenAI strict mode, including in referenced schemas, and folds their intent into descriptions. (1.3.10) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1310)
- Avoids duplicating nested optional object and array definitions, preventing compatible MCP tools from being rejected. (1.3.9) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#139)
- Optional nested properties with multiple types no longer produce exponentially large OpenAI tool payloads; payload growth remains linear as schemas become more deeply nested. (1.3.7) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#137)
- For Gemini via OpenRouter, properties without a Gemini-compatible type are rewritten into a permissive anyOf instead of being dropped, keeping expected tool fields in the contract. (1.3.6) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#136)
- The OpenAI compatibility layer removes the unsupported propertyNames keyword from structured output schemas, allowing requests using z.record() to be accepted. (1.3.6) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#136)
- Tool execute-time validation for Zod tools on Anthropic Claude 3.5 Haiku skips string min/max checks removed from the model-facing JSON Schema while preserving other validation semantics. (1.3.6) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#136)
- Schema conversion for Zod v3 is fixed for CommonJS consumers. (1.3.6) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#136)
- Fixed Claude requests failing when tool inputs use a top-level union of object schemas. (1.3.5) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#135)
- Fixes crashes when converting Zod v4 schemas containing z.record(...) with a provider compat layer attached, covering older Zod v4 versions and versions that expose ~standard.jsonSchema. (1.3.4) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#134)
- In Zod v4, nullable or optional schemas wrapping unsupported inner types, such as tuples, are passed through unchanged instead of being processed and rejected. (1.3.3) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#133)
- The Zod v4 string handler now preserves formats without textual descriptions as validation, so schemas using them keep rejecting invalid input. (1.3.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#132)
- Workflow and step type inference with Zod schemas is significantly faster and no longer causes TypeScript crashes or depth errors. (1.3.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#132)
- The Zod v4 schema handler now describes min and max date bounds according to Zod semantics, avoiding swapped or impossible constraints sent to the model. (1.3.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#132)
- Fixed a type error when passing jsonSchema() or a Schema object from @ai-sdk/provider-utils as inputSchema, so no cast is needed. (1.3.1) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#131)
- Fixed schema compatibility type declarations so JSON Schema types are bundled correctly. (1.2.12) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1212)
- Rewrites JSON Schema 2020-12 keywords into the OpenAPI 3.0 Schema Object subset Gemini expects, fixing REST tool calls for discriminated unions, lazy schemas, and tuples. (1.2.11) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1211)
- Generated schemas for Zod 4 transforms now describe the pre-transform input the model must produce, fixing structured output and tool calling. (1.2.11) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1211)
- Fixed schema conversion so Gemini accepts broad nullable tool parameters. (1.2.10) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#1210)
- MCP tools using JSON Schema draft 2020-12 now validate correctly instead of throwing “no schema with key or ref” errors. (1.2.9) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#129)
- MCP tools with recursive JSON Schema refs stay serializable when loaded. (1.2.9) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#129)
- Improved compatibility for structured outputs and tool calls, fixing validation for optional, nullable, and defaulted fields and ISO date strings returned for date fields. (1.2.8) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#128)
- Fixed ESM imports for Zod JSON Schema helpers, avoiding createRequire-related issues while preserving support for zod/v3 and zod/v4. (1.2.7) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#127)
- Mastra agent and client structured-output APIs accept schemas from either zod/v3 or zod/v4, with TypeScript compatibility for both. (1.2.7) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#127)
- The Zod v4 adapter translates Mastra draft target names to Zod v4 names, preventing invalid-target warnings and restoring the generated $schema field. (1.2.6) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#126)
- The Zod v3 adapter supports `draft-2020-12` and `draft-04` targets and translates `zod-to-json-schema` target names to standard-schema target names, fixing unsupported-target errors when serializing tool schemas. (1.2.6) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#126)
- MCP tools using allOf in their JSON Schema no longer throw an unsupported ZodIntersection error; intersection types are flattened and merged into a single object schema across provider compatibility layers. (1.2.5) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#125)
- Lazily loads createRequire to fix an “Uncaught (in promise) TypeError: lzt.createRequire is not a function” error. (1.2.4) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#124)
- The fallback now uses Node.js createRequire instead of esbuild’s require shim, fixing the “Dynamic require of zod/v4 is not supported” error when consumed by ESM bundles. (1.2.3) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#123)
- Published types now allow AI SDK v5 schemas to resolve correctly for consumers. (1.2.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#122)
- Improved schema conversion detection so JSON Schema generation works more reliably across runtime setups and avoids false `z.toJSONSchema is not available` errors for compatible Zod versions. (1.2.2) — [release notes](https://github.com/mastra-ai/mastra/blob/a15924e709dd5d9439a6c102901c326ab0ec77fb/packages/schema-compat/CHANGELOG.md#122)