Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(mastra): relax output schema so API nulls and extra keys pass validation (#3585)
Serhii Zghamaaaabf5e2a699
diff --git a/.changeset/mastra-output-schema-nullable.md b/.changeset/mastra-output-schema-nullable.mdnew file mode 100644index 000000000..0da4eda63--- /dev/null+++ b/.changeset/mastra-output-schema-nullable.md@@ -0,0 +1,5 @@+---+'@composio/mastra': patch+---++Relax the Mastra provider output schema so real third-party API responses are no longer rejected by Mastra's output validation (which dropped the data and substituted an error). Before compilation the output schema is made lenient: every typed node becomes nullable, objects allow extra keys (`additionalProperties: true`), `enum`/`const` are widened to also admit `null`, and `required` is dropped (APIs omit unset fields rather than returning `null` for them). All of these only widen what validates, so previously-valid output is unaffected.diff --git a/ts/packages/providers/mastra/src/index.ts b/ts/packages/providers/mastra/src/index.tsindex 08be5946a..ffa75a5c7 100644--- a/ts/packages/providers/mastra/src/index.ts+++ b/ts/packages/providers/mastra/src/index.ts@@ -20,6 +20,7 @@ import {} from '@composio/core';import { applyCompatLayer } from '@mastra/schema-compat';import { createTool } from '@mastra/core/tools';+import { relaxOutputSchema } from './relax-output-schema';export type MastraTool = ReturnType<typeof createTool>;@@ -125,11 +126,19 @@ export class MastraProvider extends BaseAgenticProvider<mode: 'jsonSchema',});+ // Relax the output schema before compiling it: Composio's API-supplied+ // output schemas are strict (non-nullable primitives, additionalProperties+ // false), but third-party APIs return `null` for unset optional fields and+ // sometimes extra keys. Mastra validates results against this schema and+ // drops mismatching data, so without this every such response is truncated.+ // See https://github.com/ComposioHQ/composio/issues/3047.const outputSchema = applyCompatLayer({- schema: dereferenceJsonSchema(tool.outputParameters ?? {}, {- onUnresolved: 'sentinel',- onReplace,- }),+ schema: relaxOutputSchema(+ dereferenceJsonSchema(tool.outputParameters ?? {}, {+ onUnresolved: 'sentinel',+ onReplace,+ })+ ),compatLayers: [],mode: 'jsonSchema',});diff --git a/ts/packages/providers/mastra/src/relax-output-schema.ts b/ts/packages/providers/mastra/src/relax-output-schema.tsnew file mode 100644index 000000000..b708633c6--- /dev/null+++ b/ts/packages/providers/mastra/src/relax-output-schema.ts@@ -0,0 +1,127 @@+/**+ * Output-schema leniency for the Mastra provider.+ *+ * Mastra validates every tool result against the tool's `outputSchema` via+ * `validateToolOutput`; on a mismatch it drops the data and substitutes an+ * error. Composio's API-supplied output schemas, however, are strict: optional+ * fields are typed as non-nullable primitives (`{ type: 'string' }`) and+ * objects carry `additionalProperties: false`. Real third-party APIs (Linear,+ * Notion, Jira, Slack, …) routinely return `null` for unset optional fields and+ * occasionally extra keys, so strict validation rejects perfectly good+ * responses and truncates the tool output the model sees.+ *+ * Output validation of opaque third-party pass-through payloads provides little+ * value and causes real breakage, so we relax the output schema before handing+ * it to `@mastra/schema-compat`:+ *+ * - every typed node is made nullable (`type: 'string'` → `['string', 'null']`)+ * - objects with `additionalProperties: false` (or unset) allow extra keys+ * - `enum`/`const` are widened to also admit `null` — they constrain the+ * *value* independently of `type`, so making the type nullable is not enough+ * - `required` is dropped, since real APIs omit unset fields entirely rather+ * than returning `null` for them, so requiring any field rejects good output+ *+ * All four changes only *widen* what validates, so any payload that passed+ * before still passes — there is no behavioural change for already-valid output.+ *+ * See https://github.com/ComposioHQ/composio/issues/3047.+ */++// JSON-Schema keywords whose values are themselves schemas and sit in a+// *positive* position, so relaxing them widens the parent (recurse into them).+//+// `not` is deliberately excluded: it negates its subschema, so relaxing the+// inner schema (e.g. making it nullable) would *narrow* what the parent admits —+// a `null` valid under `not: { type: 'string' }` would start failing. That is+// the opposite of this helper's only-widen guarantee, so `not` is left as-is.+const SUBSCHEMA_KEYS = ['items', 'additionalItems', 'contains'] as const;+// Keywords whose values are arrays of schemas.+const SUBSCHEMA_LIST_KEYS = ['anyOf', 'oneOf', 'allOf', 'prefixItems'] as const;+// Keywords whose values are maps of name -> schema.+const SUBSCHEMA_MAP_KEYS = ['properties', 'patternProperties', '$defs', 'definitions'] as const;++function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++function addNullToType(type: unknown): unknown {+ if (typeof type === 'string') {+ return type === 'null' ? type : [type, 'null'];+ }+ if (Array.isArray(type)) {+ return type.includes('null') ? type : [...type, 'null'];+ }+ return type;+}++/**+ * Recursively returns a leniency-relaxed copy of a JSON schema for use as a+ * Mastra `outputSchema`. The input is never mutated.+ */+export function relaxOutputSchema<T>(schema: T): T {+ if (!isPlainObject(schema)) return schema;++ const result: Record<string, unknown> = { ...schema };++ // Decide object-ness from the *original* type before it is rewritten below.+ const originalType = result.type;+ const isObjectSchema =+ originalType === 'object' ||+ (Array.isArray(originalType) && originalType.includes('object')) ||+ 'properties' in result ||+ 'patternProperties' in result;++ // Make any typed node nullable so a `null` from the upstream API validates.+ if ('type' in result) {+ result.type = addNullToType(result.type);+ }++ // `enum`/`const` restrict the value regardless of `type`, so a nullable type+ // alone would still reject a `null`. Widen them to admit `null` too; `const`+ // (a single allowed value) becomes a two-member nullable `enum`.+ if ('const' in result) {+ result.enum = [result.const, null];+ delete result.const;+ } else if (Array.isArray(result.enum) && !result.enum.includes(null)) {+ result.enum = [...result.enum, null];+ }++ // Drop `required`: third-party APIs omit unset fields entirely (not just+ // return `null`), so requiring any field would reject otherwise-valid output.+ if ('required' in result) {+ delete result.required;+ }++ // Allow extra keys on objects that forbid (or omit) additional properties.+ // A sub-schema value is preserved and recursed into instead of overwritten.+ if (isPlainObject(result.additionalProperties)) {+ result.additionalProperties = relaxOutputSchema(result.additionalProperties);+ } else if (+ isObjectSchema &&+ (result.additionalProperties === false || result.additionalProperties === undefined)+ ) {+ result.additionalProperties = true;+ }++ for (const key of SUBSCHEMA_KEYS) {+ if (key in result) result[key] = relaxOutputSchema(result[key]);+ }++ for (const key of SUBSCHEMA_LIST_KEYS) {+ const value = result[key];+ if (Array.isArray(value)) {+ result[key] = value.map(entry => relaxOutputSchema(entry));+ }+ }++ for (const key of SUBSCHEMA_MAP_KEYS) {+ const value = result[key];+ if (isPlainObject(value)) {+ result[key] = Object.fromEntries(+ Object.entries(value).map(([name, sub]) => [name, relaxOutputSchema(sub)])+ );+ }+ }++ return result as T;+}diff --git a/ts/packages/providers/mastra/test/mastra-ref.test.ts b/ts/packages/providers/mastra/test/mastra-ref.test.tsindex 13fb64a64..273472f0c 100644--- a/ts/packages/providers/mastra/test/mastra-ref.test.ts+++ b/ts/packages/providers/mastra/test/mastra-ref.test.ts@@ -91,7 +91,10 @@ describe('MastraProvider regression: $ref in JSON Schema', () => {it('preserves type info from Draft-7 `definitions` on the output schema', () => {const skuProp = findProperty(unwrapSchema(wrapped.outputSchema), 'sku');expect(skuProp).toBeDefined();- expect(skuProp?.type).toBe('string');+ // The output schema is relaxed to be nullable (issue #3047), so the+ // dereferenced `string` becomes `['string', 'null']` — the type info from+ // `definitions` is still preserved (not degraded to a permissive anyOf).+ expect(skuProp?.type).toEqual(['string', 'null']);});it('leaves no $ref in the produced schemas', () => {diff --git a/ts/packages/providers/mastra/test/mastra.test.ts b/ts/packages/providers/mastra/test/mastra.test.tsindex a28b925e9..910fdeed7 100644--- a/ts/packages/providers/mastra/test/mastra.test.ts+++ b/ts/packages/providers/mastra/test/mastra.test.ts@@ -40,6 +40,24 @@ vi.mock('@mastra/schema-compat', async () => {};});+// Expected `originalSchema` for the standard mockTool output after the+// leniency relaxation applied in wrapTool (issue #3047): typed nodes become+// nullable and the object allows extra keys. All tools below spread `mockTool`,+// so they share this output shape.+const RELAXED_MOCK_OUTPUT_SCHEMA = {+ type: 'mock-zod-schema',+ originalSchema: {+ type: ['object', 'null'],+ additionalProperties: true,+ properties: {+ result: {+ type: ['string', 'null'],+ description: 'Test result',+ },+ },+ },+};+describe('MastraProvider', () => {let provider: MastraProvider;let mockTool: Tool;@@ -113,7 +131,7 @@ describe('MastraProvider', () => {id: mockTool.slug,description: mockTool.description,inputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.inputParameters },- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});@@ -153,7 +171,7 @@ describe('MastraProvider', () => {id: toolWithoutInputParams.slug,description: toolWithoutInputParams.description,inputSchema: { type: 'mock-zod-schema', originalSchema: {} },- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});@@ -197,7 +215,7 @@ describe('MastraProvider', () => {id: toolWithoutDescription.slug,description: '',inputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.inputParameters },- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});@@ -308,14 +326,14 @@ describe('MastraProvider', () => {id: mockTool.slug,description: mockTool.description,inputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.inputParameters },- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});expect(createTool).toHaveBeenCalledWith({id: anotherTool.slug,description: anotherTool.description,inputSchema: { type: 'mock-zod-schema', originalSchema: anotherTool.inputParameters },- outputSchema: { type: 'mock-zod-schema', originalSchema: anotherTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});});@@ -559,7 +577,7 @@ describe('MastraProvider', () => {additionalProperties: false,},},- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});});@@ -608,7 +626,7 @@ describe('MastraProvider', () => {required: ['required_field'],},},- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});});@@ -637,7 +655,7 @@ describe('MastraProvider', () => {description: 'A string parameter',},},- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});});@@ -657,7 +675,7 @@ describe('MastraProvider', () => {id: toolWithoutInputParams.slug,description: toolWithoutInputParams.description,inputSchema: { type: 'mock-zod-schema', originalSchema: {} },- outputSchema: { type: 'mock-zod-schema', originalSchema: mockTool.outputParameters },+ outputSchema: RELAXED_MOCK_OUTPUT_SCHEMA,execute: expect.any(Function),});});diff --git a/ts/packages/providers/mastra/test/output-validation.integration.test.ts b/ts/packages/providers/mastra/test/output-validation.integration.test.tsnew file mode 100644index 000000000..42d4cffec--- /dev/null+++ b/ts/packages/providers/mastra/test/output-validation.integration.test.ts@@ -0,0 +1,125 @@+import { describe, it, expect } from 'vitest';+import { applyCompatLayer, convertSchemaToZod } from '@mastra/schema-compat';+import { relaxOutputSchema } from '../src/relax-output-schema';++/**+ * Integration regression test for issue #3047.+ *+ * `mastra.test.ts` mocks `@mastra/schema-compat`, so it verifies *that*+ * `wrapTool` relaxes the output schema but never exercises the real validation.+ * This test runs the full production chain instead — the same one `wrapTool`+ * drives at tool-execution time:+ *+ * relaxOutputSchema → applyCompatLayer(mode: 'jsonSchema') → convertSchemaToZod → parse+ *+ * `convertSchemaToZod` is the JSON-Schema → Zod conversion Mastra performs+ * internally before `validateToolOutput` checks a tool result. The test proves+ * that the relaxation makes a real third-party API response (with `null`+ * optional fields and extra keys) survive validation instead of being dropped+ * and replaced by an error — and that no data is truncated in the process.+ *+ * See https://github.com/ComposioHQ/composio/issues/3047.+ */++// A strict Composio-style output schema: optional fields typed as non-nullable+// primitives, objects closed with `additionalProperties: false` — exactly the+// shape the Composio API emits for connector tools.+const STRICT_OUTPUT_SCHEMA = {+ type: 'object',+ additionalProperties: false,+ properties: {+ data: {+ type: 'object',+ additionalProperties: false,+ properties: {+ id: { type: 'string' },+ title: { type: 'string' },+ avatarUrl: { type: 'string' },+ description: { type: 'string' },+ assignee: {+ type: 'object',+ additionalProperties: false,+ properties: { name: { type: 'string' } },+ },+ },+ },+ },+};++// A realistic third-party response: `null` for unset optional fields plus an+// unexpected extra key — what Linear / Notion / Jira / Slack actually return.+const REAL_API_PAYLOAD = {+ data: {+ id: 'iss_123',+ title: 'Fix the thing',+ avatarUrl: null,+ description: null,+ assignee: null,+ unexpectedExtraKey: 'present',+ },+};++/** Mirror of the validation Mastra runs on a tool result. */+function compileForValidation(schema: object) {+ const jsonSchema = applyCompatLayer({ schema, compatLayers: [], mode: 'jsonSchema' });+ return convertSchemaToZod(jsonSchema as object);+}++describe('Mastra output validation against real schema-compat (issue #3047)', () => {+ it('documents the bug: the strict schema rejects null optional fields', () => {+ const validator = compileForValidation(STRICT_OUTPUT_SCHEMA);+ const result = validator.safeParse(REAL_API_PAYLOAD);+ // Without the relaxation Mastra would drop this data and substitute an error.+ expect(result.success).toBe(false);+ });++ it('relaxed schema accepts the payload, preserving null values and extra keys', () => {+ const validator = compileForValidation(relaxOutputSchema(STRICT_OUTPUT_SCHEMA));+ const result = validator.safeParse(REAL_API_PAYLOAD);++ expect(result.success).toBe(true);+ // Nothing is truncated: nulls and the extra key survive untouched.+ expect(result.data).toEqual(REAL_API_PAYLOAD);+ });++ it('relaxed schema lets an enum field return null, but still rejects bogus values', () => {+ const schema = {+ type: 'object',+ additionalProperties: false,+ properties: { status: { type: 'string', enum: ['open', 'closed'] } },+ };+ const strict = compileForValidation(schema);+ const relaxed = compileForValidation(relaxOutputSchema(schema));++ expect(strict.safeParse({ status: null }).success).toBe(false); // the gap+ expect(relaxed.safeParse({ status: null }).success).toBe(true); // fixed+ expect(relaxed.safeParse({ status: 'open' }).success).toBe(true); // still valid+ expect(relaxed.safeParse({ status: 'nope' }).success).toBe(false); // still constrained+ });++ it('relaxed schema accepts a response that omits a required field', () => {+ const schema = {+ type: 'object',+ additionalProperties: false,+ required: ['id', 'title'],+ properties: { id: { type: 'string' }, title: { type: 'string' } },+ };+ const strict = compileForValidation(schema);+ const relaxed = compileForValidation(relaxOutputSchema(schema));++ expect(strict.safeParse({ id: 'iss_1' }).success).toBe(false); // the gap+ expect(relaxed.safeParse({ id: 'iss_1' }).success).toBe(true); // fixed+ });++ it('never narrows validation through a `not` keyword', () => {+ const schema = { not: { type: 'string' } }; // "must not be a string" — null is valid+ const strict = compileForValidation(schema);+ const relaxed = compileForValidation(relaxOutputSchema(schema));++ // Relaxing `not`'s subschema would make these previously-valid values fail.+ expect(strict.safeParse(null).success).toBe(true);+ expect(relaxed.safeParse(null).success).toBe(true); // still valid, not narrowed+ expect(relaxed.safeParse(42).success).toBe(true); // still valid+ expect(relaxed.safeParse('str').success).toBe(false); // constraint preserved+ });+});diff --git a/ts/packages/providers/mastra/test/relax-output-schema.test.ts b/ts/packages/providers/mastra/test/relax-output-schema.test.tsnew file mode 100644index 000000000..98e85a86c--- /dev/null+++ b/ts/packages/providers/mastra/test/relax-output-schema.test.ts@@ -0,0 +1,180 @@+import { describe, it, expect } from 'vitest';+import { relaxOutputSchema } from '../src/relax-output-schema';++describe('relaxOutputSchema (issue #3047)', () => {+ it('adds "null" to a primitive type so API nulls validate', () => {+ expect(relaxOutputSchema({ type: 'string' })).toEqual({ type: ['string', 'null'] });+ });++ it('appends "null" to an existing type array without duplicating it', () => {+ expect(relaxOutputSchema({ type: ['string', 'number'] })).toEqual({+ type: ['string', 'number', 'null'],+ });+ expect(relaxOutputSchema({ type: ['string', 'null'] })).toEqual({+ type: ['string', 'null'],+ });+ });++ it('relaxes nested object properties, flips additionalProperties false → true, and drops required', () => {+ const input = {+ type: 'object',+ additionalProperties: false,+ properties: {+ avatarUrl: { type: 'string' },+ assignee: {+ type: 'object',+ additionalProperties: false,+ properties: { name: { type: 'string' } },+ },+ },+ required: ['avatarUrl'],+ };++ // `required` is dropped (API may omit `avatarUrl` entirely), nested objects+ // are relaxed the same way, and nothing else is altered.+ expect(relaxOutputSchema(input)).toEqual({+ type: ['object', 'null'],+ additionalProperties: true,+ properties: {+ avatarUrl: { type: ['string', 'null'] },+ assignee: {+ type: ['object', 'null'],+ additionalProperties: true,+ properties: { name: { type: ['string', 'null'] } },+ },+ },+ });+ });++ it('drops required so an omitted field still validates (issue #3047 gap)', () => {+ const input = {+ type: 'object',+ additionalProperties: false,+ required: ['id', 'name'],+ properties: { id: { type: 'string' }, name: { type: 'string' } },+ };+ expect(relaxOutputSchema(input)).toEqual({+ type: ['object', 'null'],+ additionalProperties: true,+ properties: { id: { type: ['string', 'null'] }, name: { type: ['string', 'null'] } },+ });+ });++ it('widens an enum to also admit null without dropping the other members', () => {+ expect(relaxOutputSchema({ type: 'string', enum: ['open', 'closed'] })).toEqual({+ type: ['string', 'null'],+ enum: ['open', 'closed', null],+ });+ // idempotent: an enum that already allows null is left as-is+ expect(relaxOutputSchema({ type: 'string', enum: ['open', null] })).toEqual({+ type: ['string', 'null'],+ enum: ['open', null],+ });+ });++ it('converts const into a nullable two-member enum', () => {+ expect(relaxOutputSchema({ const: 'fixed' })).toEqual({ enum: ['fixed', null] });+ });++ it('adds additionalProperties: true to an object that omits it', () => {+ expect(relaxOutputSchema({ type: 'object', properties: {} })).toEqual({+ type: ['object', 'null'],+ additionalProperties: true,+ properties: {},+ });+ });++ it('does not touch additionalProperties on non-object (primitive) nodes', () => {+ expect(relaxOutputSchema({ type: 'string' })).not.toHaveProperty('additionalProperties');+ });++ it('preserves and recurses into a schema-valued additionalProperties', () => {+ const input = {+ type: 'object',+ additionalProperties: { type: 'string' },+ };+ expect(relaxOutputSchema(input)).toEqual({+ type: ['object', 'null'],+ additionalProperties: { type: ['string', 'null'] },+ });+ });++ it('relaxes array item schemas', () => {+ const input = {+ type: 'array',+ items: {+ type: 'object',+ additionalProperties: false,+ properties: { id: { type: 'number' } },+ },+ };+ expect(relaxOutputSchema(input)).toEqual({+ type: ['array', 'null'],+ items: {+ type: ['object', 'null'],+ additionalProperties: true,+ properties: { id: { type: ['number', 'null'] } },+ },+ });+ });++ it('recurses into anyOf/oneOf/allOf branches', () => {+ const input = {+ anyOf: [{ type: 'string' }, { type: 'object', properties: { a: { type: 'boolean' } } }],+ };+ expect(relaxOutputSchema(input)).toEqual({+ anyOf: [+ { type: ['string', 'null'] },+ {+ type: ['object', 'null'],+ additionalProperties: true,+ properties: { a: { type: ['boolean', 'null'] } },+ },+ ],+ });+ });++ it('leaves a `not` subschema untouched so relaxation never narrows validation', () => {+ // `not` negates its subschema: relaxing the inner schema (making it+ // nullable) would *reject* values that were valid before (e.g. `null` under+ // `not: { type: 'string' }`), violating the only-widen invariant. The inner+ // schema must therefore be preserved verbatim, even when nested in an object+ // that is itself relaxed.+ expect(relaxOutputSchema({ not: { type: 'string' } })).toEqual({ not: { type: 'string' } });+ expect(+ relaxOutputSchema({+ type: 'object',+ additionalProperties: false,+ properties: { x: { not: { type: 'string' } } },+ })+ ).toEqual({+ type: ['object', 'null'],+ additionalProperties: true,+ properties: { x: { not: { type: 'string' } } },+ });+ });++ it('returns an empty schema unchanged (no type, no properties)', () => {+ expect(relaxOutputSchema({})).toEqual({});+ });++ it('does not mutate the input schema (including required/enum/const paths)', () => {+ const input = {+ type: 'object',+ additionalProperties: false,+ required: ['a'],+ properties: {+ a: { type: 'string', enum: ['x', 'y'] },+ b: { const: 'z' },+ },+ };+ const snapshot = JSON.parse(JSON.stringify(input));+ relaxOutputSchema(input);+ expect(input).toEqual(snapshot);+ });++ it('passes through non-object inputs untouched', () => {+ expect(relaxOutputSchema(null as unknown as object)).toBeNull();+ expect(relaxOutputSchema(undefined as unknown as object)).toBeUndefined();+ });+});