0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/packages/schema-compat
History 2026-11-12 21:12:29 +00:00
..
__recordings__ test(core): replay real-provider completion-feedback test (T78) from recordings (#26010) 2026-10-06 15:43:22 -05:00
src Fix OpenAPI request schemas for defaulted and transformed fields (#30187) 2026-11-12 06:33:48 -08:00
CHANGELOG.md chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
package.json chore: version - exit prerelease mode 2026-11-12 21:12:29 +00:00
README.md chore(*): Update/unify/add READMEs (#22858) 2026-09-02 14:36:59 +02:00
tsconfig.build.json chore: fix go-to-definition using tsc declaration maps (#6089) 2025-07-30 15:41:00 -07:00
tsconfig.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
tsdown.config.ts Enforce JSON Schema formats in MCP tool validation (#30113) 2026-11-11 14:16:55 -08:00
turbo.json chore: migrate package builds to tsdown (#19829) 2026-07-28 12:32:21 +02:00
vitest.config.ts feat: Add Standard Schema support with Zod v3/v4 compatibility (#12238) 2026-03-09 17:51:41 +01:00

@mastra/schema-compat

Schema compatibility utilities that adapt Zod and JSON schemas to the different subsets and formats supported by AI model providers. Mastra uses these layers when tool inputs or structured outputs contain schema features a provider cannot accept directly.

Installation

npm install @mastra/schema-compat

Usage

Apply a provider layer to a Zod schema before passing it to an AI SDK API:

import { applyCompatLayer, OpenAISchemaCompatLayer } from '@mastra/schema-compat';
import { z } from 'zod';

const model = {
  provider: 'openai.chat',
  modelId: 'gpt-5.2',
  supportsStructuredOutputs: true,
};

const schema = z.object({
  name: z.string().email(),
  tags: z.array(z.string()).min(1),
});

const compatibleSchema = applyCompatLayer({
  schema,
  compatLayers: [new OpenAISchemaCompatLayer(model)],
  mode: 'aiSdkSchema',
});

Documentation

The package includes compatibility layers for Anthropic, DeepSeek, Google, Meta, OpenAI, and OpenAI reasoning models. A layer decides whether it applies to the supplied model information, selects the provider's schema target, and rewrites unsupported checks or structures without changing the application's source schema.

applyCompatLayer() chooses the first applicable layer and returns either an AI SDK schema or JSON Schema. convertZodSchemaToAISDKSchema() converts Zod directly, while convertSchemaToZod() converts supported schema inputs back to Zod. Standard Schema helpers are available for extracting schemas, converting them to JSON Schema, and applying OpenAI compatibility transforms to tools.

The package supports both Zod v3 and v4. SchemaCompatLayerV3 and SchemaCompatLayerV4 expose version-specific APIs, while SchemaCompatLayer dispatches based on the schema version. Utilities such as prepareJsonSchemaForOpenAIStrictMode() and ensureAllPropertiesRequired() handle strict structured-output requirements.

Provider layers commonly remove unsupported refinements, convert validation rules into descriptions, normalize nullable and union types, and target JSON Schema 7 or OpenAPI-compatible output as required by the provider.

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.