Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(mastra): resolve $ref in tool schemas before applyCompatLayer [PLEN-2244]

jkomynocc673b654cd2
diff --git a/.changeset/fix-mastra-ref-dereference.md b/.changeset/fix-mastra-ref-dereference.md
new file mode 100644
index 000000000..f3ab8ce4d
--- /dev/null
+++ b/.changeset/fix-mastra-ref-dereference.md
@@ -0,0 +1,12 @@
+---
+'@composio/core': patch
+'@composio/mastra': patch
+---
+
+Resolve internal JSON Schema `$ref` pointers (`#/$defs/...` and `#/definitions/...`) before handing tool parameters to `@mastra/schema-compat`. Composio tools whose schemas use `$defs`/`definitions` — legal under Draft 7 and 2020-12 — no longer trigger the AJV `can't resolve reference …` error, and the resolved type information from `$defs` survives the JSON-Schema → Zod → JSON-Schema round-trip instead of being silently degraded to a permissive `anyOf`.
+
+- New `dereferenceJsonSchema` helper exported from `@composio/core` performs the inline expansion. It deep-clones the input, walks every applicator reflectively (so future JSON Schema keywords are covered), shallow-merges sibling keywords next to `$ref` per Draft 2020-12 semantics, breaks cycles with `{ type: 'object', additionalProperties: true }` (matching the upstream guidance in [mastra-ai/mastra#15341](https://github.com/mastra-ai/mastra/issues/15341)), and strips `$defs`/`definitions` once everything reachable is inlined. External (`http://`/`https://`) `$ref` pointers are left untouched.
+- `@composio/mastra` calls the helper inside `wrapTool` for both `inputParameters` and `outputParameters`.
+- `@mastra/schema-compat` dependency floor raised to `^1.2.9` so users automatically receive [PR #15400](https://github.com/mastra-ai/mastra/pull/15400)'s recursive-`$ref` handling.
+
+Closes [PLEN-2244](https://linear.app/composio/issue/PLEN-2244/mastra-provider-schema-validation-error-cant-resolve-reference).
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 491570cb7..4207e2253 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1397,8 +1397,8 @@ importers:
ts/packages/providers/mastra:
dependencies:
'@mastra/schema-compat':
- specifier: ^1.0.0
- version: 1.1.0([email protected])
+ specifier: ^1.2.9
+ version: 1.2.9([email protected])
devDependencies:
'@composio/core':
specifier: workspace:*
@@ -3004,6 +3004,12 @@ packages:
peerDependencies:
zod: ^3.25.0 || ^4.0.0
+ '@mastra/[email protected]':
+ resolution: {integrity: sha512-1/RgazXqi1Wdyx8aR81CVS+sRyzlTGUL1YhhHkSULoEY8aXs58bvWkH/6iixlYsY0xGvn+0OPLCeSRkBCtDx4Q==}
+ engines: {node: '>=22.13.0'}
+ peerDependencies:
+ zod: ^3.25.0 || ^4.0.0
+
'@modelcontextprotocol/[email protected]':
resolution: {integrity: sha512-Y5RmPncpiDtTXDbLKswIJzTqu2hyBKxTNsgKqKclDbhIgg1wgtf1fRuvxgTnRfcnxtvvgbIEcqUOzZrJ6iSReg==}
engines: {node: '>=18'}
@@ -8246,6 +8252,14 @@ snapshots:
zod-from-json-schema-v3: [email protected]
zod-to-json-schema: 3.25.1([email protected])
+ dependencies:
+ json-schema-to-zod: 2.7.0
+ zod: 4.3.6
+ zod-from-json-schema: 0.5.2
+ zod-from-json-schema-v3: [email protected]
+ zod-to-json-schema: 3.25.2([email protected])
+
'@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected])':
dependencies:
'@hono/node-server': 1.19.9([email protected])
diff --git a/ts/packages/core/src/index.ts b/ts/packages/core/src/index.ts
index 02fcef40c..cdb8a9db2 100644
--- a/ts/packages/core/src/index.ts
+++ b/ts/packages/core/src/index.ts
@@ -4,7 +4,11 @@ export { OpenAIProvider } from './provider/OpenAIProvider';
export { ComposioProvider } from './provider/ComposioProvider';
export { BaseNonAgenticProvider, BaseAgenticProvider } from './provider/BaseProvider';
export type { BaseComposioProvider } from './provider/BaseProvider';
-export { jsonSchemaToZodSchema, removeNonRequiredProperties } from './utils/jsonSchema';
+export {
+ dereferenceJsonSchema,
+ jsonSchemaToZodSchema,
+ removeNonRequiredProperties,
+} from './utils/jsonSchema';
export { getExtensionFromMimeType } from './utils/mime';
export { AuthScheme } from './models/AuthScheme';
export { MCP } from './models/MCP';
diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.ts
index 807be25f2..5747fa1dd 100644
--- a/ts/packages/core/src/utils/jsonSchema.ts
+++ b/ts/packages/core/src/utils/jsonSchema.ts
@@ -1,7 +1,174 @@
import { z } from 'zod/v3';
-import { JsonSchemaToZodError } from '../errors';
+import { JsonSchemaRefResolutionError, JsonSchemaToZodError } from '../errors';
import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
+const MAX_REF_CHAIN_DEPTH = 100;
+const CYCLE_BREAK_SENTINEL = Object.freeze({ type: 'object', additionalProperties: true });
+const INTERNAL_REF_PREFIX = '#';
+
+const decodePointerSegment = (segment: string): string =>
+ segment.replace(/~1/g, '/').replace(/~0/g, '~');
+
+const resolvePointer = (
+ root: Record<string, unknown>,
+ pointer: string
+): { target: unknown; canonical: string } => {
+ if (pointer === '#' || pointer === '') {
+ return { target: root, canonical: '#' };
+ }
+ if (!pointer.startsWith('#/')) {
+ throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
+ meta: { ref: pointer },
+ });
+ }
+ const segments = pointer.slice(2).split('/').map(decodePointerSegment);
+ let cursor: unknown = root;
+ for (const segment of segments) {
+ if (cursor === null || typeof cursor !== 'object') {
+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
+ meta: { ref: pointer, failedAt: segment },
+ });
+ }
+ if (Array.isArray(cursor)) {
+ const index = Number(segment);
+ if (!Number.isInteger(index) || index < 0 || index >= cursor.length) {
+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
+ meta: { ref: pointer, failedAt: segment },
+ });
+ }
+ cursor = cursor[index];
+ } else {
+ const obj = cursor as Record<string, unknown>;
+ if (!Object.prototype.hasOwnProperty.call(obj, segment)) {
+ throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
+ meta: { ref: pointer, failedAt: segment },
+ });
+ }
+ cursor = obj[segment];
+ }
+ }
+ return { target: cursor, canonical: pointer };
+};
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+ value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and the
+ * legacy `#/definitions/...`) so the returned schema can be safely handed
+ * to consumers — like AJV in `@mastra/schema-compat` — that don't tolerate
+ * unresolved references.
+ *
+ * The traversal is reflective (no allow-list of JSON Schema keywords), so
+ * future applicators (`unevaluatedProperties`, `dependentSchemas`, …) are
+ * covered automatically. Sibling keywords next to `$ref` are shallow-merged
+ * per Draft 2020-12 semantics — the sibling wins on collision so a caller's
+ * `description` or `default` overrides the target's. Recursive `$ref`
+ * chains are broken with `{ type: 'object', additionalProperties: true }`,
+ * matching the upstream Mastra recommendation in
+ * {@link https://github.com/mastra-ai/mastra/issues/15341 mastra-ai/mastra#15341}.
+ *
+ * The input schema is not mutated: every node is deep-cloned. `$defs` and
+ * `definitions` are stripped from the returned root once everything
+ * reachable is inlined — AJV strict-mode otherwise complains about unused
+ * definitions.
+ *
+ * External `$ref` pointers (`http://`, `https://`, `file://`, …) are left
+ * untouched: the caller may forward them to a consumer that resolves them
+ * natively.
+ *
+ * @param schema - The JSON Schema to dereference. May be any plain object.
+ * @returns A new schema with internal `$ref` pointers inlined.
+ *
+ * @throws {JsonSchemaRefResolutionError} When an internal pointer is
+ * malformed, points at a missing target, or chains past the depth cap.
+ *
+ * @example
+ * ```ts
+ * dereferenceJsonSchema({
+ * type: 'object',
+ * properties: { user: { $ref: '#/$defs/User' } },
+ * $defs: { User: { type: 'object', properties: { id: { type: 'string' } } } },
+ * });
+ * // {
+ * // type: 'object',
+ * // properties: {
+ * // user: { type: 'object', properties: { id: { type: 'string' } } },
+ * // },
+ * // }
+ * ```
+ */
+export function dereferenceJsonSchema<T = unknown>(schema: T): T {
+ if (!isPlainObject(schema)) return schema;
+
+ const root = schema as Record<string, unknown>;
+
+ const walk = (node: unknown, path: string[], depth: number): unknown => {
+ if (Array.isArray(node)) {
+ return node.map((item, index) => walk(item, [...path, String(index)], depth));
+ }
+ if (!isPlainObject(node)) return node;
+
+ if (typeof node.$ref === 'string') {
+ const ref = node.$ref;
+ // External refs are out of scope; leave them alone.
+ if (!ref.startsWith(INTERNAL_REF_PREFIX)) {
+ const cloned: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(node)) {
+ cloned[key] = walk(value, [...path, key], depth);
+ }
+ return cloned;
+ }
+
+ if (depth >= MAX_REF_CHAIN_DEPTH) {
+ throw new JsonSchemaRefResolutionError(
+ `JSON Schema $ref chain exceeded depth cap (${MAX_REF_CHAIN_DEPTH}): ${ref}`,
+ { meta: { ref } }
+ );
+ }
+
+ // Cycle detection: if `ref` already appears in the current path, this
+ // resolution would re-enter itself. Break the cycle.
+ if (path.includes(`@ref:${ref}`)) {
+ return { ...CYCLE_BREAK_SENTINEL };
+ }
+
+ const { target } = resolvePointer(root, ref);
+ const resolved = walk(target, [...path, `@ref:${ref}`], depth + 1);
+
+ // Shallow-merge sibling keywords (Draft 2020-12 semantics: siblings win
+ // on collision). Draft 7 ignores siblings entirely, but the Composio
+ // tool surface admits both drafts so we honor siblings for safety.
+ const { $ref: _omit, ...siblings } = node;
+ void _omit;
+ if (Object.keys(siblings).length === 0) {
+ return resolved;
+ }
+ if (!isPlainObject(resolved)) {
+ return resolved;
+ }
+ const merged: Record<string, unknown> = { ...resolved };
+ for (const [key, value] of Object.entries(siblings)) {
+ merged[key] = walk(value, [...path, key], depth);
+ }
+ return merged;
+ }
+
+ const cloned: Record<string, unknown> = {};
+ for (const [key, value] of Object.entries(node)) {
+ cloned[key] = walk(value, [...path, key], depth);
+ }
+ return cloned;
+ };
+
+ const out = walk(root, [], 0);
+ if (isPlainObject(out)) {
+ delete out.$defs;
+ delete out.definitions;
+ }
+ return out as T;
+}
+
/**
* Removes all non-required properties from the schema
*
diff --git a/ts/packages/providers/mastra/package.json b/ts/packages/providers/mastra/package.json
index ed66e7fb6..acd45d9a4 100644
--- a/ts/packages/providers/mastra/package.json
+++ b/ts/packages/providers/mastra/package.json
@@ -57,6 +57,6 @@
"zod": "catalog:"
},
"dependencies": {
- "@mastra/schema-compat": "^1.0.0"
+ "@mastra/schema-compat": "^1.2.9"
}
}
diff --git a/ts/packages/providers/mastra/src/index.ts b/ts/packages/providers/mastra/src/index.ts
index dccae6054..b3cc3d192 100644
--- a/ts/packages/providers/mastra/src/index.ts
+++ b/ts/packages/providers/mastra/src/index.ts
@@ -11,6 +11,7 @@ import {
Tool,
ExecuteToolFn,
McpUrlResponse,
+ dereferenceJsonSchema,
removeNonRequiredProperties,
} from '@composio/core';
import { applyCompatLayer } from '@mastra/schema-compat';
@@ -90,14 +91,20 @@ export class MastraProvider extends BaseAgenticProvider<
)
: inputParams;
+ // Inline internal $ref pointers before handing the schema to
+ // @mastra/schema-compat. AJV (bundled inside schema-compat) refuses to
+ // compile a schema with unresolved $ref, and the upstream JSON-Schema →
+ // Zod converter silently degrades $ref-typed properties to a permissive
+ // anyOf — losing the type info from $defs. See [PLEN-2244] and
+ // mastra-ai/mastra#15341.
const inputSchema = applyCompatLayer({
- schema: parameters ?? {},
+ schema: dereferenceJsonSchema(parameters ?? {}),
compatLayers: [],
mode: 'jsonSchema',
});
const outputSchema = applyCompatLayer({
- schema: tool.outputParameters ?? {},
+ schema: dereferenceJsonSchema(tool.outputParameters ?? {}),
compatLayers: [],
mode: 'jsonSchema',
});