@mastra/schema-compat 1.3.8-alpha.0 → 1.3.8-alpha.1

package/README.md

@@ -1,144 +1,53 @@
 # @mastra/schema-compat
 
-Schema compatibility layer for Mastra.ai that provides compatibility fixes for different AI model providers when using Zod schemas with tools.
+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
 
 ```bash
-pnpm add @mastra/schema-compat
+npm install @mastra/schema-compat
 ```
 
 ## Usage
 
-### Basic Usage
-
-The package provides a base `SchemaCompatLayer` class that you can extend to create custom compatibility layers for different AI model providers:
-
-```typescript
-import { SchemaCompatLayer } from '@mastra/schema-compat';
-import type { LanguageModelV1 } from 'ai';
-
-class MyCustomCompat extends SchemaCompatLayer {
-  constructor(model: LanguageModelV1) {
-    super(model);
-  }
-
-  shouldApply(): boolean {
-    return this.getModel().provider === 'my-provider';
-  }
-
-  getSchemaTarget() {
-    return 'jsonSchema7';
-  }
-
-  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
-    // Your custom processing logic here
-    return value;
-  }
-}
-```
-
-### Schema Processing
-
-The package includes pre-built compatibility layers for popular AI providers:
-
-Use the `applyCompatLayer` function to automatically apply the right compatibility layer:
+Apply a provider layer to a Zod schema before passing it to an AI SDK API:
 
 ```typescript
-import { applyCompatLayer, OpenAISchemaCompatLayer, AnthropicSchemaCompatLayer } from '@mastra/schema-compat';
-import { yourCustomCompatibilityLayer } from './customCompatibilityLayer';
+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(),
-  preferences: z.array(z.string()).min(1),
+  tags: z.array(z.string()).min(1),
 });
 
-const compatLayers = [
-  new OpenAISchemaCompatLayer(model),
-  new AnthropicSchemaCompatLayer(model),
-  new yourCustomCompatibilityLayer(model),
-];
-
-// Automatically applies the first matching compatibility
-const result = applyCompatLayer({
+const compatibleSchema = applyCompatLayer({
   schema,
-  compatLayers,
-  mode: 'aiSdkSchema', // or 'jsonSchema'
+  compatLayers: [new OpenAISchemaCompatLayer(model)],
+  mode: 'aiSdkSchema',
 });
 ```
 
-### Schema Building Utilities
+## Documentation
 
-The package also provides utility functions for schema conversion:
+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.
 
-```typescript
-import { convertZodSchemaToAISDKSchema, convertSchemaToZod } from '@mastra/schema-compat';
-import { z } from 'zod';
-import { jsonSchema } from 'ai';
+`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.
 
-const zodSchema = z.object({
-  name: z.string(),
-  age: z.number(),
-});
+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.
 
-// Convert Zod to AI SDK Schema
-const aiSchema = convertZodSchemaToAISDKSchema(zodSchema);
+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.
 
-// Convert AI SDK Schema back to Zod
-const aiSdkSchema = jsonSchema({
-  type: 'object',
-  properties: {
-    name: { type: 'string' },
-  },
-});
-const backToZod = convertSchemaToZod(aiSdkSchema);
-```
+## Changelog
 
-## API Reference
+See the [package changelog](https://github.com/mastra-ai/mastra/blob/main/packages/schema-compat/CHANGELOG.md) for version history and release notes.
 
-### Classes
+## Support
 
-- `SchemaCompatLayer` - Base abstract class for creating compatibility layers
-- `AnthropicSchemaCompatLayer` - Compatibility for Anthropic Claude models
-- `OpenAISchemaCompatLayer` - Compatibility for OpenAI models (without structured outputs)
-- `OpenAIReasoningSchemaCompatLayer` - Compatibility for OpenAI reasoning models (o1 series)
-- `GoogleSchemaCompatLayer` - Compatibility for Google Gemini models
-- `DeepSeekSchemaCompatLayer` - Compatibility for DeepSeek models
-- `MetaSchemaCompatLayer` - Compatibility for Meta Llama models
-
-### Functions
-
-- `applyCompatLayer(options)` - Process schema with automatic compatibility detection
-- `convertZodSchemaToAISDKSchema(zodSchema, target?)` - Convert Zod schema to AI SDK Schema
-- `convertSchemaToZod(schema)` - Convert AI SDK Schema to Zod schema
-
-### Types and Constants
-
-- `StringCheckType`, `NumberCheckType`, `ArrayCheckType` - Check types for validation
-- `UnsupportedZodType`, `SupportedZodType`, `AllZodType` - Zod type classifications
-- `ZodShape`, `ShapeKey`, `ShapeValue` - Utility types for Zod schemas
-- `ALL_STRING_CHECKS`, `ALL_NUMBER_CHECKS`, `ALL_ARRAY_CHECKS` - Validation constraint arrays
-- `SUPPORTED_ZOD_TYPES`, `UNSUPPORTED_ZOD_TYPES` - Type classification arrays
-
-## Provider-Specific Behavior
-
-Different AI providers have varying levels of support for JSON Schema features. This package handles these differences automatically:
-
-- **OpenAI**: Removes certain string validations for models without structured outputs
-- **Anthropic**: Handles complex nested schemas with proper constraint descriptions
-- **Google**: Uses OpenAPI 3.0 schema format for better compatibility
-- **DeepSeek**: Converts advanced string patterns to descriptions
-- **Meta**: Optimizes array and union type handling
-
-## Testing
-
-The package includes comprehensive tests covering all functionality:
-
-```bash
-# Run tests
-pnpm test
-
-# Run tests in watch mode
-pnpm test --watch
-```
+We have an [open community Discord](https://discord.gg/mastra-ai). Come and say hello and let us know if you have any questions or need any help getting things running.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/schema-compat",
-  "version": "1.3.8-alpha.0",
+  "version": "1.3.8-alpha.1",
   "description": "Tool schema compatibility layer for Mastra.ai",
   "type": "module",
   "main": "dist/index.js",
@@ -117,10 +117,10 @@
     "zod-v3": "npm:zod@^3.25.76",
     "zod-to-json-schema": "^3.25.2",
     "zod-from-json-schema-v3": "npm:zod-from-json-schema@^0.0.5",
-    "@internal/ai-sdk-v5": "0.0.76",
-    "@internal/ai-v6": "0.0.76",
     "@internal/ai-sdk-v4": "0.0.76",
+    "@internal/ai-sdk-v5": "0.0.76",
     "@internal/lint": "0.0.129",
+    "@internal/ai-v6": "0.0.76",
     "@internal/llm-recorder": "0.0.65",
     "@internal/test-utils": "0.0.65",
     "@internal/types-builder": "0.0.104"