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.

test(mastra): add red regression tests for $ref handling [PLEN-2244]

jkomyno5300bf8ba7ca
diff --git a/ts/packages/core/src/errors/ValidationErrors.ts b/ts/packages/core/src/errors/ValidationErrors.ts
index 5386ebaa0..ad62d7577 100644
--- a/ts/packages/core/src/errors/ValidationErrors.ts
+++ b/ts/packages/core/src/errors/ValidationErrors.ts
@@ -9,6 +9,7 @@ import { ComposioError, ComposioErrorOptions } from './ComposioError';
export const ValidationErrorCodes = {
VALIDATION_ERROR: 'VALIDATION_ERROR',
JSON_SCHEMA_TO_ZOD_ERROR: 'JSON_SCHEMA_TO_ZOD_ERROR',
+ JSON_SCHEMA_REF_RESOLUTION_ERROR: 'JSON_SCHEMA_REF_RESOLUTION_ERROR',
} as const;
export class ValidationError extends ComposioError {
@@ -79,3 +80,20 @@ export class JsonSchemaToZodError extends ComposioError {
});
}
}
+
+/**
+ * Thrown when a JSON Schema `$ref` pointer cannot be resolved against the
+ * document. Used by `dereferenceJsonSchema` to surface malformed pointers,
+ * missing `$defs`/`definitions` targets, or chains exceeding the depth cap.
+ */
+export class JsonSchemaRefResolutionError extends ComposioError {
+ constructor(
+ message: string = 'Failed to resolve JSON Schema $ref',
+ options: ComposioErrorOptions = {}
+ ) {
+ super(message, {
+ ...options,
+ code: options.code || ValidationErrorCodes.JSON_SCHEMA_REF_RESOLUTION_ERROR,
+ });
+ }
+}
diff --git a/ts/packages/core/test/utils/jsonSchema.test.ts b/ts/packages/core/test/utils/jsonSchema.test.ts
new file mode 100644
index 000000000..b86225acd
--- /dev/null
+++ b/ts/packages/core/test/utils/jsonSchema.test.ts
@@ -0,0 +1,227 @@
+import { describe, it, expect } from 'vitest';
+import { dereferenceJsonSchema } from '../../src/utils/jsonSchema';
+import { JsonSchemaRefResolutionError } from '../../src/errors/ValidationErrors';
+
+const containsRef = (value: unknown): boolean => {
+ if (value === null || typeof value !== 'object') return false;
+ if (Array.isArray(value)) return value.some(containsRef);
+ if ('$ref' in (value as Record<string, unknown>)) return true;
+ return Object.values(value as Record<string, unknown>).some(containsRef);
+};
+
+describe('dereferenceJsonSchema', () => {
+ it('inlines a single internal $ref under $defs', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { user: { $ref: '#/$defs/User' } },
+ required: ['user'],
+ $defs: { User: { type: 'string' } },
+ });
+
+ expect(out).toEqual({
+ type: 'object',
+ properties: { user: { type: 'string' } },
+ required: ['user'],
+ });
+ expect(containsRef(out)).toBe(false);
+ });
+
+ it('resolves a chain of refs A -> B -> C', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/A' } },
+ $defs: {
+ A: { $ref: '#/$defs/B' },
+ B: { $ref: '#/$defs/C' },
+ C: { type: 'integer' },
+ },
+ });
+
+ expect(containsRef(out)).toBe(false);
+ expect((out as { properties: { v: unknown } }).properties.v).toEqual({ type: 'integer' });
+ });
+
+ it('walks containers reflectively (items, oneOf, anyOf, allOf, not, additionalProperties, patternProperties, prefixItems)', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: {
+ a: { type: 'array', items: { $ref: '#/$defs/Leaf' } },
+ b: { oneOf: [{ $ref: '#/$defs/Leaf' }, { type: 'null' }] },
+ c: { anyOf: [{ $ref: '#/$defs/Leaf' }] },
+ d: { allOf: [{ $ref: '#/$defs/Leaf' }] },
+ e: { not: { $ref: '#/$defs/Leaf' } },
+ f: { type: 'object', additionalProperties: { $ref: '#/$defs/Leaf' } },
+ g: {
+ type: 'object',
+ patternProperties: { '^x_': { $ref: '#/$defs/Leaf' } },
+ },
+ h: { type: 'array', prefixItems: [{ $ref: '#/$defs/Leaf' }] },
+ },
+ $defs: { Leaf: { type: 'string' } },
+ });
+
+ expect(containsRef(out)).toBe(false);
+ });
+
+ it('resolves Draft 7 legacy `definitions`', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { name: { $ref: '#/definitions/Name' } },
+ definitions: { Name: { type: 'string', minLength: 1 } },
+ });
+
+ expect(containsRef(out)).toBe(false);
+ expect((out as { properties: { name: unknown } }).properties.name).toEqual({
+ type: 'string',
+ minLength: 1,
+ });
+ });
+
+ it('mixes $defs and definitions transitively', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { v: { $ref: '#/definitions/A' } },
+ definitions: { A: { $ref: '#/$defs/B' } },
+ $defs: { B: { type: 'boolean' } },
+ });
+
+ expect(containsRef(out)).toBe(false);
+ expect((out as { properties: { v: unknown } }).properties.v).toEqual({ type: 'boolean' });
+ });
+
+ it('shallow-merges sibling keywords next to $ref (Draft 2020-12 semantics; siblings win on collision)', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: {
+ v: {
+ $ref: '#/$defs/Foo',
+ description: 'caller override',
+ default: null,
+ },
+ },
+ $defs: {
+ Foo: { type: 'string', description: 'target description' },
+ },
+ });
+
+ const v = (out as { properties: { v: Record<string, unknown> } }).properties.v;
+ expect(v.type).toBe('string');
+ expect(v.description).toBe('caller override');
+ expect(v.default).toBeNull();
+ expect(containsRef(out)).toBe(false);
+ });
+
+ it('breaks recursive $ref cycles with a permissive object sentinel', () => {
+ const out = dereferenceJsonSchema({
+ $ref: '#/$defs/Tree',
+ $defs: {
+ Tree: {
+ type: 'object',
+ properties: {
+ children: { type: 'array', items: { $ref: '#/$defs/Tree' } },
+ },
+ },
+ },
+ });
+
+ expect((out as { type: string }).type).toBe('object');
+ const children = (
+ out as {
+ properties: { children: { items: { type: string; additionalProperties: boolean } } };
+ }
+ ).properties.children;
+ expect(children.items).toEqual({ type: 'object', additionalProperties: true });
+ expect(containsRef(out)).toBe(false);
+ });
+
+ it('strips $defs and definitions from the returned root schema', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { x: { $ref: '#/$defs/Foo' } },
+ $defs: { Foo: { type: 'integer' } },
+ definitions: { Bar: { type: 'string' } },
+ }) as Record<string, unknown>;
+
+ expect(out.$defs).toBeUndefined();
+ expect(out.definitions).toBeUndefined();
+ });
+
+ it('throws JsonSchemaRefResolutionError when target is missing', () => {
+ expect(() =>
+ dereferenceJsonSchema({
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/Missing' } },
+ $defs: {},
+ })
+ ).toThrow(JsonSchemaRefResolutionError);
+ });
+
+ it('throws JsonSchemaRefResolutionError when chain depth exceeds the cap', () => {
+ const $defs: Record<string, unknown> = {};
+ for (let i = 0; i < 200; i++) {
+ $defs[`A${i}`] = { $ref: i + 1 < 200 ? `#/$defs/A${i + 1}` : '#/$defs/A0' };
+ }
+ expect(() =>
+ dereferenceJsonSchema({
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/A0' } },
+ $defs,
+ })
+ ).toThrow(JsonSchemaRefResolutionError);
+ });
+
+ it('leaves external $ref pointers untouched', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { v: { $ref: 'https://example.com/Foo' } },
+ });
+
+ expect((out as { properties: { v: { $ref: string } } }).properties.v.$ref).toBe(
+ 'https://example.com/Foo'
+ );
+ });
+
+ it('does not mutate the input schema', () => {
+ const input = {
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/Foo' } },
+ $defs: { Foo: { type: 'string' } },
+ };
+ const snapshot = structuredClone(input);
+ dereferenceJsonSchema(input);
+ expect(input).toEqual(snapshot);
+ });
+
+ it('decodes JSON Pointer escape sequences (~1 -> /, ~0 -> ~) in the correct order', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: {
+ a: { $ref: '#/$defs/with~1slash' },
+ b: { $ref: '#/$defs/with~0tilde' },
+ c: { $ref: '#/$defs/tilde-then-slash~01' },
+ },
+ $defs: {
+ 'with/slash': { type: 'string' },
+ 'with~tilde': { type: 'integer' },
+ 'tilde-then-slash~1': { type: 'boolean' },
+ },
+ } as unknown as Record<string, unknown>);
+
+ const props = (out as { properties: Record<string, { type: string }> }).properties;
+ expect(props.a.type).toBe('string');
+ expect(props.b.type).toBe('integer');
+ expect(props.c.type).toBe('boolean');
+ });
+
+ it('resolves array-index pointers (#/$defs/foo/oneOf/0)', () => {
+ const out = dereferenceJsonSchema({
+ type: 'object',
+ properties: { v: { $ref: '#/$defs/foo/oneOf/0' } },
+ $defs: {
+ foo: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+ },
+ } as unknown as Record<string, unknown>);
+
+ expect((out as { properties: { v: { type: string } } }).properties.v.type).toBe('string');
+ });
+});
diff --git a/ts/packages/providers/mastra/test/mastra-ref.test.ts b/ts/packages/providers/mastra/test/mastra-ref.test.ts
new file mode 100644
index 000000000..fbdfce1e8
--- /dev/null
+++ b/ts/packages/providers/mastra/test/mastra-ref.test.ts
@@ -0,0 +1,135 @@
+/**
+ * Integration test for the Mastra provider against the **real**
+ * `@mastra/schema-compat` package (no `vi.mock` for it). This is the regression
+ * test for [PLEN-2244]: a Composio tool whose `inputParameters` carry a `$ref`
+ * (legal under both Draft 7 and 2020-12).
+ *
+ * Without dereferencing, `applyCompatLayer` silently *degrades* the `$ref`-typed
+ * property to a permissive `anyOf` of all primitives — losing the type
+ * information from `$defs`. This test asserts the post-wrap `inputSchema`
+ * preserves the structure described by `$defs`, which is only possible if
+ * `$ref` is resolved before the conversion.
+ *
+ * Vitest mock scoping is per-file by default, so the top-level `vi.mock` for
+ * `@mastra/schema-compat` in `mastra.test.ts` does **not** leak into this file.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import type { Tool } from '@composio/core';
+import { MastraProvider } from '../src';
+
+const containsRef = (value: unknown): boolean => {
+ if (value === null || typeof value !== 'object') return false;
+ if (Array.isArray(value)) return value.some(containsRef);
+ if ('$ref' in (value as Record<string, unknown>)) return true;
+ return Object.values(value as Record<string, unknown>).some(containsRef);
+};
+
+const findProperty = (schema: unknown, key: string): Record<string, unknown> | undefined => {
+ if (schema === null || typeof schema !== 'object') return undefined;
+ const node = schema as Record<string, unknown>;
+ if (node.properties && typeof node.properties === 'object') {
+ const props = node.properties as Record<string, unknown>;
+ if (key in props) return props[key] as Record<string, unknown>;
+ for (const value of Object.values(props)) {
+ const found = findProperty(value, key);
+ if (found) return found;
+ }
+ }
+ for (const value of Object.values(node)) {
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ const found = findProperty(item, key);
+ if (found) return found;
+ }
+ } else if (typeof value === 'object' && value !== null) {
+ const found = findProperty(value, key);
+ if (found) return found;
+ }
+ }
+ return undefined;
+};
+
+const refTool: Tool = {
+ slug: 'PLEN_2244_TOOL',
+ name: 'PLEN-2244 Tool',
+ description: 'Tool whose schema carries internal $ref pointers',
+ toolkit: { slug: 'plen2244', name: 'PLEN 2244' },
+ version: '20260430_00',
+ availableVersions: ['20260430_00'],
+ tags: [],
+ inputParameters: {
+ type: 'object',
+ properties: { user: { $ref: '#/$defs/User' } as never },
+ required: ['user'],
+ $defs: {
+ User: {
+ type: 'object',
+ properties: { id: { type: 'string' } },
+ required: ['id'],
+ },
+ },
+ } as unknown as Tool['inputParameters'],
+ outputParameters: {
+ type: 'object',
+ properties: { item: { $ref: '#/definitions/Item' } as never },
+ definitions: {
+ Item: {
+ type: 'object',
+ properties: { sku: { type: 'string' } },
+ required: ['sku'],
+ },
+ },
+ } as unknown as Tool['outputParameters'],
+};
+
+describe('MastraProvider regression: PLEN-2244 ($ref in JSON Schema)', () => {
+ it('does not throw when wrapping a tool whose schema uses $ref / $defs', () => {
+ const provider = new MastraProvider();
+ const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ provider._setExecuteToolFn(executeToolFn);
+
+ expect(() => provider.wrapTool(refTool, executeToolFn)).not.toThrow();
+ });
+
+ it('preserves type information from $defs (does not degrade $ref to permissive anyOf)', () => {
+ const provider = new MastraProvider();
+ const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ provider._setExecuteToolFn(executeToolFn);
+
+ const wrapped = provider.wrapTool(refTool, executeToolFn) as { inputSchema: unknown };
+
+ // Without the dereference step, `$ref` is silently dropped during
+ // JSON-Schema → Zod → JSON-Schema round-trip and the `id` field disappears
+ // entirely (the property gets degraded to a permissive `anyOf`).
+ const idProp = findProperty(wrapped.inputSchema, 'id');
+ expect(idProp).toBeDefined();
+ expect(idProp?.type).toBe('string');
+ });
+
+ it('preserves type information from `definitions` on outputParameters (Draft 7)', () => {
+ const provider = new MastraProvider();
+ const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ provider._setExecuteToolFn(executeToolFn);
+
+ const wrapped = provider.wrapTool(refTool, executeToolFn) as { outputSchema: unknown };
+
+ const skuProp = findProperty(wrapped.outputSchema, 'sku');
+ expect(skuProp).toBeDefined();
+ expect(skuProp?.type).toBe('string');
+ });
+
+ it('does not leave any $ref in the produced schemas', () => {
+ const provider = new MastraProvider();
+ const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ provider._setExecuteToolFn(executeToolFn);
+
+ const wrapped = provider.wrapTool(refTool, executeToolFn) as {
+ inputSchema: unknown;
+ outputSchema: unknown;
+ };
+
+ expect(containsRef(wrapped.inputSchema)).toBe(false);
+ expect(containsRef(wrapped.outputSchema)).toBe(false);
+ });
+});