@mastra/schema-compat 0.0.0-ai-v5-20250625173645

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@mastra/schema-compat",
+  "version": "0.0.0-ai-v5-20250625173645",
+  "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": {
+    "json-schema": "^0.4.0",
+    "zod-from-json-schema": "^0.0.5",
+    "zod-to-json-schema": "^3.24.5"
+  },
+  "peerDependencies": {
+    "ai": "5.0.0-beta.1",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/json-schema": "^7.0.15",
+    "ai": "5.0.0-beta.1",
+    "eslint": "^9.28.0",
+    "tsup": "^8.5.0",
+    "@types/node": "^20.19.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.3",
+    "zod": "^3.25.57",
+    "@internal/lint": "0.0.0-ai-v5-20250625173645"
+  },
+  "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,39 @@
+// 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,
+  // Re-usable type predicates
+  isOptional,
+  isObj,
+  isArr,
+  isUnion,
+  isString,
+  isNumber,
+} 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,48 @@
+import type { ZodTypeAny } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer, isArr, isObj, isOptional, isString, isUnion } from '../schema-compatibility';
+import type { AllZodType, SchemaCompatModel } from '../schema-compatibility';
+
+export class AnthropicSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: SchemaCompatModel) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    return this.getModel().modelId.includes('claude');
+  }
+
+  processZodType(value: ZodTypeAny): ZodTypeAny {
+    if (isOptional(value)) {
+      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);
+    } else if (isObj(value)) {
+      return this.defaultZodObjectHandler(value);
+    } else if (isArr(value)) {
+      return this.defaultZodArrayHandler(value, []);
+    } else if (isUnion(value)) {
+      return this.defaultZodUnionHandler(value);
+    } else if (isString(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
+
+      if (this.getModel().modelId.includes('claude-3.5-haiku')) {
+        return this.defaultZodStringHandler(value, ['max', 'min']);
+      } else {
+        return value;
+      }
+    }
+
+    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,35 @@
+import type { ZodTypeAny } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer, isArr, isObj, isOptional, isString, isUnion } from '../schema-compatibility';
+import type { SchemaCompatModel } from '../schema-compatibility';
+
+export class DeepSeekSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: SchemaCompatModel) {
+    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(value: ZodTypeAny): ZodTypeAny {
+    if (isOptional(value)) {
+      return this.defaultZodOptionalHandler(value, ['ZodObject', 'ZodArray', 'ZodUnion', 'ZodString', 'ZodNumber']);
+    } else if (isObj(value)) {
+      return this.defaultZodObjectHandler(value);
+    } else if (isArr(value)) {
+      return this.defaultZodArrayHandler(value, ['min', 'max']);
+    } else if (isUnion(value)) {
+      return this.defaultZodUnionHandler(value);
+    } else if (isString(value)) {
+      return this.defaultZodStringHandler(value);
+    }
+
+    return value;
+  }
+}

package/src/provider-compats/google.ts

@@ -0,0 +1,55 @@
+import type { ZodTypeAny } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import {
+  SchemaCompatLayer,
+  UNSUPPORTED_ZOD_TYPES,
+  isArr,
+  isNumber,
+  isObj,
+  isOptional,
+  isString,
+  isUnion,
+} from '../schema-compatibility';
+import type { SchemaCompatModel } from '../schema-compatibility';
+
+export class GoogleSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: SchemaCompatModel) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    return this.getModel().provider.includes('google') || this.getModel().modelId.includes('google');
+  }
+
+  processZodType(value: ZodTypeAny): ZodTypeAny {
+    if (isOptional(value)) {
+      return this.defaultZodOptionalHandler(value, [
+        'ZodObject',
+        'ZodArray',
+        'ZodUnion',
+        'ZodString',
+        'ZodNumber',
+        ...UNSUPPORTED_ZOD_TYPES,
+      ]);
+    } else if (isObj(value)) {
+      return this.defaultZodObjectHandler(value);
+    } else if (isArr(value)) {
+      return this.defaultZodArrayHandler(value, []);
+    } else if (isUnion(value)) {
+      return this.defaultZodUnionHandler(value);
+    } else if (isString(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
+      return this.defaultZodStringHandler(value);
+    } else if (isNumber(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
+      return this.defaultZodNumberHandler(value);
+    }
+    return this.defaultUnsupportedZodTypeHandler(value);
+  }
+}

package/src/provider-compats/meta.ts

@@ -0,0 +1,36 @@
+import type { ZodTypeAny } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer, isArr, isNumber, isObj, isOptional, isString, isUnion } from '../schema-compatibility';
+import type { SchemaCompatModel } from '../schema-compatibility';
+
+export class MetaSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: SchemaCompatModel) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return 'jsonSchema7';
+  }
+
+  shouldApply(): boolean {
+    return this.getModel().modelId.includes('meta');
+  }
+
+  processZodType(value: ZodTypeAny): ZodTypeAny {
+    if (isOptional(value)) {
+      return this.defaultZodOptionalHandler(value, ['ZodObject', 'ZodArray', 'ZodUnion', 'ZodString', 'ZodNumber']);
+    } else if (isObj(value)) {
+      return this.defaultZodObjectHandler(value);
+    } else if (isArr(value)) {
+      return this.defaultZodArrayHandler(value, ['min', 'max']);
+    } else if (isUnion(value)) {
+      return this.defaultZodUnionHandler(value);
+    } else if (isNumber(value)) {
+      return this.defaultZodNumberHandler(value);
+    } else if (isString(value)) {
+      return this.defaultZodStringHandler(value);
+    }
+
+    return value;
+  }
+}

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

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import type { ZodTypeAny } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import {
+  SchemaCompatLayer,
+  isArr,
+  isDate,
+  isDefault,
+  isNumber,
+  isObj,
+  isOptional,
+  isString,
+  isUnion,
+} from '../schema-compatibility';
+import type { SchemaCompatModel } from '../schema-compatibility';
+
+export class OpenAIReasoningSchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: SchemaCompatModel) {
+    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()) && // <- supportsStructuredOutputs no longer exists
+      this.isReasoningModel() &&
+      (this.getModel().provider.includes(`openai`) || this.getModel().modelId.includes(`openai`))
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  processZodType(value: ZodTypeAny): ZodTypeAny {
+    if (isOptional(value)) {
+      const innerZodType = this.processZodType(value._def.innerType);
+      return innerZodType.nullable();
+    } else if (isObj(value)) {
+      return this.defaultZodObjectHandler(value);
+    } else if (isArr(value)) {
+      return this.defaultZodArrayHandler(value);
+    } else if (isUnion(value)) {
+      return this.defaultZodUnionHandler(value);
+    } else if (isDefault(value)) {
+      const defaultDef = value._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(innerType);
+      if (description) {
+        result = result.describe(description);
+      }
+      return result;
+    } else if (isNumber(value)) {
+      return this.defaultZodNumberHandler(value);
+    } else if (isString(value)) {
+      return this.defaultZodStringHandler(value);
+    } else if (isDate(value)) {
+      return this.defaultZodDateHandler(value);
+    } else if (value._def.typeName === '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`,
+        );
+    }
+
+    return this.defaultUnsupportedZodTypeHandler(value);
+  }
+}

package/src/provider-compats/openai.ts

@@ -0,0 +1,56 @@
+import type { ZodTypeAny } from 'zod';
+import type { Targets } from 'zod-to-json-schema';
+import { SchemaCompatLayer, isArr, isObj, isOptional, isString, isUnion } from '../schema-compatibility';
+import type { SchemaCompatModel, StringCheckType } from '../schema-compatibility';
+
+export class OpenAISchemaCompatLayer extends SchemaCompatLayer {
+  constructor(model: SchemaCompatModel) {
+    super(model);
+  }
+
+  getSchemaTarget(): Targets | undefined {
+    return `jsonSchema7`;
+  }
+
+  shouldApply(): boolean {
+    if (
+      // !this.getModel().supportsStructuredOutputs && // <- TODO: this no longer exists, do we need it?
+      this.getModel().provider.includes(`openai`) ||
+      this.getModel().modelId.includes(`openai`)
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  processZodType(value: ZodTypeAny): ZodTypeAny {
+    if (isOptional(value)) {
+      return this.defaultZodOptionalHandler(value, [
+        'ZodObject',
+        'ZodArray',
+        'ZodUnion',
+        'ZodString',
+        'ZodNever',
+        'ZodUndefined',
+        'ZodTuple',
+      ]);
+    } else if (isObj(value)) {
+      return this.defaultZodObjectHandler(value);
+    } else if (isUnion(value)) {
+      return this.defaultZodUnionHandler(value);
+    } else if (isArr(value)) {
+      return this.defaultZodArrayHandler(value);
+    } else if (isString(value)) {
+      const model = this.getModel();
+      const checks: StringCheckType[] = ['emoji'];
+
+      if (model.modelId.includes('gpt-4o-mini')) {
+        checks.push('regex');
+      }
+      return this.defaultZodStringHandler(value, checks);
+    }
+
+    return this.defaultUnsupportedZodTypeHandler(value, ['ZodNever', 'ZodUndefined', 'ZodTuple']);
+  }
+}