@mastra/schema-compat 0.10.2-alpha.2

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mastra/schema-compat",
+  "version": "0.10.2-alpha.2",
+  "description": "Tool schema compatibility layer for Mastra.ai",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [
+    "mastra",
+    "schema",
+    "tool",
+    "compatibility",
+    "zod"
+  ],
+  "author": "",
+  "license": "Elastic-2.0",
+  "dependencies": {
+    "zod-from-json-schema": "^0.0.5",
+    "zod-to-json-schema": "^3.24.5",
+    "json-schema": "^0.4.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0",
+    "ai": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.57",
+    "@types/json-schema": "^7.0.15",
+    "eslint": "^9.28.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.2",
+    "zod": "^3.24.3",
+    "ai": "4.3.16",
+    "@internal/lint": "0.0.10"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --experimental-dts --clean --treeshake=smallest --splitting",
+    "build:watch": "pnpm build --watch",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Schema compatibility base class and related types
+export {
+  SchemaCompatLayer,
+  // Constants
+  ALL_STRING_CHECKS,
+  ALL_NUMBER_CHECKS,
+  ALL_ARRAY_CHECKS,
+  UNSUPPORTED_ZOD_TYPES,
+  SUPPORTED_ZOD_TYPES,
+  ALL_ZOD_TYPES,
+  // Types
+  type StringCheckType,
+  type NumberCheckType,
+  type ArrayCheckType,
+  type UnsupportedZodType,
+  type SupportedZodType,
+  type AllZodType,
+  type ZodShape,
+  type ShapeKey,
+  type ShapeValue,
+} from './schema-compatibility';
+
+// Utility functions
+export { convertZodSchemaToAISDKSchema, applyCompatLayer, convertSchemaToZod } from './utils';
+
+// Provider compatibility implementations
+export { AnthropicSchemaCompatLayer } from './provider-compats/anthropic';
+export { DeepSeekSchemaCompatLayer } from './provider-compats/deepseek';
+export { GoogleSchemaCompatLayer } from './provider-compats/google';
+export { MetaSchemaCompatLayer } from './provider-compats/meta';
+export { OpenAISchemaCompatLayer } from './provider-compats/openai';
+export { OpenAIReasoningSchemaCompatLayer } from './provider-compats/openai-reasoning';

package/src/provider-compats/anthropic.ts

@@ -0,0 +1,54 @@
+import type { LanguageModelV1 } from 'ai';
+import type { z } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer } from '../schema-compatibility';
+import type { ShapeValue, AllZodType } from '../schema-compatibility';
+
+export class AnthropicSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: LanguageModelV1) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    return this.getModel().modelId.includes('claude');
+  }
+
+  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
+    switch (value._def.typeName) {
+      case 'ZodOptional':
+        const handleTypes: AllZodType[] = ['ZodObject', 'ZodArray', 'ZodUnion', 'ZodNever', 'ZodUndefined'];
+        if (this.getModel().modelId.includes('claude-3.5-haiku')) handleTypes.push('ZodString');
+        if (this.getModel().modelId.includes('claude-3.7')) handleTypes.push('ZodTuple');
+
+        return this.defaultZodOptionalHandler(value, handleTypes);
+      case 'ZodObject': {
+        return this.defaultZodObjectHandler(value);
+      }
+      case 'ZodArray': {
+        return this.defaultZodArrayHandler(value, []);
+      }
+      case 'ZodUnion': {
+        return this.defaultZodUnionHandler(value);
+      }
+      // the claude-3.5-haiku model support these properties but the model doesn't respect them, but it respects them when they're
+      // added to the tool description
+      case 'ZodString': {
+        if (this.getModel().modelId.includes('claude-3.5-haiku')) {
+          return this.defaultZodStringHandler(value, ['max', 'min']);
+        } else {
+          return value as ShapeValue<T>;
+        }
+      }
+      default:
+        if (this.getModel().modelId.includes('claude-3.7')) {
+          return this.defaultUnsupportedZodTypeHandler(value, ['ZodNever', 'ZodTuple', 'ZodUndefined']);
+        } else {
+          return this.defaultUnsupportedZodTypeHandler(value, ['ZodNever', 'ZodUndefined']);
+        }
+    }
+  }
+}

package/src/provider-compats/deepseek.ts

@@ -0,0 +1,41 @@
+import type { LanguageModelV1 } from 'ai';
+import type { z } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer } from '../schema-compatibility';
+import type { ShapeValue } from '../schema-compatibility';
+
+export class DeepSeekSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: LanguageModelV1) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    // Deepseek R1 performs perfectly without this compat layer
+    return this.getModel().modelId.includes('deepseek') && !this.getModel().modelId.includes('r1');
+  }
+
+  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
+    switch (value._def.typeName) {
+      case 'ZodOptional':
+        return this.defaultZodOptionalHandler(value, ['ZodObject', 'ZodArray', 'ZodUnion', 'ZodString', 'ZodNumber']);
+      case 'ZodObject': {
+        return this.defaultZodObjectHandler(value);
+      }
+      case 'ZodArray': {
+        return this.defaultZodArrayHandler(value, ['min', 'max']);
+      }
+      case 'ZodUnion': {
+        return this.defaultZodUnionHandler(value);
+      }
+      case 'ZodString': {
+        return this.defaultZodStringHandler(value);
+      }
+      default:
+        return value as ShapeValue<T>;
+    }
+  }
+}

package/src/provider-compats/google.ts

@@ -0,0 +1,54 @@
+import type { LanguageModelV1 } from 'ai';
+import type { z } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer, UNSUPPORTED_ZOD_TYPES } from '../schema-compatibility';
+import type { ShapeValue } from '../schema-compatibility';
+
+export class GoogleSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: LanguageModelV1) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    return this.getModel().provider.includes('google') || this.getModel().modelId.includes('google');
+  }
+
+  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
+    switch (value._def.typeName) {
+      case 'ZodOptional':
+        return this.defaultZodOptionalHandler(value, [
+          'ZodObject',
+          'ZodArray',
+          'ZodUnion',
+          'ZodString',
+          'ZodNumber',
+          ...UNSUPPORTED_ZOD_TYPES,
+        ]);
+      case 'ZodObject': {
+        return this.defaultZodObjectHandler(value);
+      }
+      case 'ZodArray': {
+        return this.defaultZodArrayHandler(value, []);
+      }
+      case 'ZodUnion': {
+        return this.defaultZodUnionHandler(value);
+      }
+      // Google models support these properties but the model doesn't respect them, but it respects them when they're
+      // added to the tool description
+      case 'ZodString': {
+        return this.defaultZodStringHandler(value);
+      }
+      case 'ZodNumber': {
+        // Google models support these properties but the model doesn't respect them, but it respects them when they're
+        // added to the tool description
+        return this.defaultZodNumberHandler(value);
+      }
+      default:
+        return this.defaultUnsupportedZodTypeHandler(value);
+    }
+  }
+}

package/src/provider-compats/meta.ts

@@ -0,0 +1,43 @@
+import type { LanguageModelV1 } from 'ai';
+import type { z } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer } from '../schema-compatibility';
+import type { ShapeValue } from '../schema-compatibility';
+
+export class MetaSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: LanguageModelV1) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    return this.getModel().modelId.includes('meta');
+  }
+
+  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
+    switch (value._def.typeName) {
+      case 'ZodOptional':
+        return this.defaultZodOptionalHandler(value, ['ZodObject', 'ZodArray', 'ZodUnion', 'ZodString', 'ZodNumber']);
+      case 'ZodObject': {
+        return this.defaultZodObjectHandler(value);
+      }
+      case 'ZodArray': {
+        return this.defaultZodArrayHandler(value, ['min', 'max']);
+      }
+      case 'ZodUnion': {
+        return this.defaultZodUnionHandler(value);
+      }
+      case 'ZodNumber': {
+        return this.defaultZodNumberHandler(value);
+      }
+      case 'ZodString': {
+        return this.defaultZodStringHandler(value);
+      }
+      default:
+        return value as ShapeValue<T>;
+    }
+  }
+}

package/src/provider-compats/openai-reasoning.ts

@@ -0,0 +1,86 @@
+import type { LanguageModelV1 } from 'ai';
+import { z } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer } from '../schema-compatibility';
+import type { ShapeValue } from '../schema-compatibility';
+
+export class OpenAIReasoningSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: LanguageModelV1) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return `openApi3`;
+  }
+
+  isReasoningModel(): boolean {
+    // there isn't a good way to automatically detect reasoning models besides doing this.
+    // in the future when o5 is released this compat wont apply and we'll want to come back and update this class + our tests
+    return this.getModel().modelId.includes(`o3`) || this.getModel().modelId.includes(`o4`);
+  }
+
+  shouldApply(): boolean {
+    if (
+      (this.getModel().supportsStructuredOutputs || this.isReasoningModel()) &&
+      (this.getModel().provider.includes(`openai`) || this.getModel().modelId.includes(`openai`))
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
+    switch (value._def.typeName) {
+      case 'ZodOptional':
+        const innerZodType = this.processZodType(value._def.innerType);
+        return innerZodType.nullable() as ShapeValue<T>;
+      case 'ZodObject': {
+        return this.defaultZodObjectHandler(value);
+      }
+      case 'ZodArray': {
+        return this.defaultZodArrayHandler(value);
+      }
+      case 'ZodUnion': {
+        return this.defaultZodUnionHandler(value);
+      }
+      case 'ZodDefault': {
+        const defaultDef = (value as z.ZodDefault<any>)._def;
+        const innerType = defaultDef.innerType;
+        const defaultValue = defaultDef.defaultValue();
+        const constraints: { defaultValue?: unknown } = {};
+        if (defaultValue !== undefined) {
+          constraints.defaultValue = defaultValue;
+        }
+
+        const description = this.mergeParameterDescription(value.description, constraints);
+        let result = this.processZodType<T>(innerType);
+        if (description) {
+          result = result.describe(description);
+        }
+        return result;
+      }
+      case 'ZodNumber': {
+        return this.defaultZodNumberHandler(value);
+      }
+      case 'ZodString': {
+        return this.defaultZodStringHandler(value);
+      }
+      case 'ZodDate': {
+        return this.defaultZodDateHandler(value);
+      }
+      case 'ZodAny': {
+        // It's bad practice in the tool to use any, it's not reasonable for models that don't support that OOTB, to cast every single possible type
+        // in the schema. Usually when it's "any" it could be a json object or a union of specific types.
+        return z
+          .string()
+          .describe(
+            (value.description ?? '') +
+              `\nArgument was an "any" type, but you (the LLM) do not support "any", so it was cast to a "string" type`,
+          );
+      }
+      default:
+        return this.defaultUnsupportedZodTypeHandler(value);
+    }
+  }
+}

package/src/provider-compats/openai.ts

@@ -0,0 +1,61 @@
+import type { LanguageModelV1 } from 'ai';
+import type { z } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer } from '../schema-compatibility';
+import type { ShapeValue, StringCheckType } from '../schema-compatibility';
+
+export class OpenAISchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: LanguageModelV1) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return `jsonSchema7`;
+  }
+
+  shouldApply(): boolean {
+    if (
+      !this.getModel().supportsStructuredOutputs &&
+      (this.getModel().provider.includes(`openai`) || this.getModel().modelId.includes(`openai`))
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  processZodType<T extends z.AnyZodObject>(value: z.ZodTypeAny): ShapeValue<T> {
+    switch (value._def.typeName) {
+      case 'ZodOptional':
+        return this.defaultZodOptionalHandler(value, [
+          'ZodObject',
+          'ZodArray',
+          'ZodUnion',
+          'ZodString',
+          'ZodNever',
+          'ZodUndefined',
+          'ZodTuple',
+        ]);
+      case 'ZodObject': {
+        return this.defaultZodObjectHandler(value);
+      }
+      case 'ZodUnion': {
+        return this.defaultZodUnionHandler(value);
+      }
+      case 'ZodArray': {
+        return this.defaultZodArrayHandler(value);
+      }
+      case 'ZodString': {
+        const model = this.getModel();
+        const checks: StringCheckType[] = ['emoji'];
+
+        if (model.modelId.includes('gpt-4o-mini')) {
+          checks.push('regex');
+        }
+        return this.defaultZodStringHandler(value, checks);
+      }
+      default:
+        return this.defaultUnsupportedZodTypeHandler(value, ['ZodNever', 'ZodUndefined', 'ZodTuple']);
+    }
+  }
+}