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(json-schema-to-effect-schema): reject dynamic-key schema defects at construction

jkomyno26315ead21dc
diff --git a/ts/packages/json-schema-to-effect-schema/src/index.ts b/ts/packages/json-schema-to-effect-schema/src/index.ts
index 8f2336e44..9e74acc09 100644
--- a/ts/packages/json-schema-to-effect-schema/src/index.ts
+++ b/ts/packages/json-schema-to-effect-schema/src/index.ts
@@ -1,4 +1,4 @@
-import { Validator } from '@cfworker/json-schema';
+import { dereference, Validator } from '@cfworker/json-schema';
import type { OutputUnit, Schema as InterpreterSchema, SchemaDraft } from '@cfworker/json-schema';
import { Schema } from 'effect';
@@ -188,6 +188,102 @@ const normalizeSchemaNode = (
const normalizeJsonSchema = (schema: JsonObject): InterpreterSchema =>
normalizeSchemaNode(schema, new WeakMap()) as InterpreterSchema;
+// Walks the same child positions `normalizeSchemaNode` does, so a node is
+// visited exactly where the interpreter would descend into it.
+const forEachSchemaNode = (
+ value: unknown,
+ seen: WeakSet<object>,
+ visit: (node: JsonObject) => void
+): void => {
+ if (!isJsonObject(value) || seen.has(value)) {
+ return;
+ }
+ seen.add(value);
+ visit(value);
+
+ for (const [key, child] of Object.entries(value)) {
+ if (schemaMapKeywords.has(key) && isJsonObject(child)) {
+ for (const nested of Object.values(child)) {
+ forEachSchemaNode(nested, seen, visit);
+ }
+ } else if (schemaArrayKeywords.has(key) && Array.isArray(child)) {
+ for (const nested of child) {
+ forEachSchemaNode(nested, seen, visit);
+ }
+ } else if (schemaValueKeywords.has(key)) {
+ for (const nested of Array.isArray(child) ? child : [child]) {
+ forEachSchemaNode(nested, seen, visit);
+ }
+ }
+ }
+};
+
+const assertRegexCompiles = (pattern: string, keyword: string): void => {
+ try {
+ // The same flag `@cfworker/json-schema` compiles with, so this accepts
+ // exactly the patterns the interpreter would.
+ new RegExp(pattern, 'u');
+ } catch (cause) {
+ throw new Error(`Invalid ${keyword} regular expression ${JSON.stringify(pattern)}.`, { cause });
+ }
+};
+
+// Follows every reference reachable from one dynamic-key subschema, including
+// through the schemas those references resolve to, so a local pointer whose
+// target carries a dangling reference is caught as well.
+const assertDynamicReferencesResolve = (
+ subSchema: unknown,
+ lookup: Record<string, unknown>,
+ seen: WeakSet<object>
+): void => {
+ forEachSchemaNode(subSchema, seen, node => {
+ const ref = node.$ref;
+ if (typeof ref !== 'string') {
+ return;
+ }
+
+ const absolute = (node as { readonly __absolute_ref__?: string }).__absolute_ref__ ?? ref;
+ const target = lookup[absolute];
+ if (target === undefined) {
+ throw new Error(`Unresolved $ref ${JSON.stringify(ref)} in a dynamic-key schema.`);
+ }
+
+ assertDynamicReferencesResolve(target, lookup, seen);
+ });
+};
+
+// `@cfworker/json-schema` compiles `patternProperties` keys and resolves `$ref`
+// lazily, inside `validate`. Left alone, a defect in the schema surfaces once
+// per call through the same channel as a genuine input failure, telling the
+// caller their arguments are wrong when the tool's schema is what is broken.
+// Checking eagerly moves those defects to construction, where the CLI already
+// reports them as a compile failure against the cached schema path.
+//
+// The scope matches what the Python SDK rejects while wrapping a tool: the keys
+// of `patternProperties`, and references inside a dynamic-key subschema. A
+// reference in a declared property is deliberately left to the interpreter —
+// widening past parity would reject tool schemas that validate today.
+const assertSchemaIsInterpretable = (schema: InterpreterSchema): void => {
+ // Re-derives the lookup the `Validator` keeps private. `dereference` builds a
+ // fresh map per call and reuses the `__absolute_ref__` it already stamped, so
+ // running it a second time is consistent with the interpreter's own view.
+ const lookup = dereference(schema);
+
+ forEachSchemaNode(schema, new WeakSet(), node => {
+ const patternProperties = node.patternProperties;
+ if (isJsonObject(patternProperties)) {
+ for (const [pattern, patternSchema] of Object.entries(patternProperties)) {
+ assertRegexCompiles(pattern, 'patternProperties');
+ assertDynamicReferencesResolve(patternSchema, lookup, new WeakSet());
+ }
+ }
+
+ if (isJsonObject(node.additionalProperties)) {
+ assertDynamicReferencesResolve(node.additionalProperties, lookup, new WeakSet());
+ }
+ });
+};
+
const decodePointer = (pointer: string): ReadonlyArray<string> => {
if (pointer === '#' || pointer === '') {
return [];
@@ -356,6 +452,7 @@ export const jsonSchemaToEffectSchema = (
): Schema.Schema<unknown> => {
const normalizedSchema = normalizeJsonSchema(jsonSchema);
const validator = new Validator(normalizedSchema, options.draft ?? '7', false);
+ assertSchemaIsInterpretable(normalizedSchema);
const formatIssues = options.formatIssues ?? defaultFormatIssues;
return Schema.Unknown.pipe(
@@ -364,6 +461,11 @@ export const jsonSchemaToEffectSchema = (
try {
validation = validator.validate(input);
} catch (error) {
+ // Schema defects are rejected at construction, so what reaches here is
+ // input the interpreter cannot represent at all — a `bigint`, `symbol`,
+ // `function`, or `undefined`. That is a property of the input, so it
+ // belongs in the filter. A string is `Schema.filter`'s shorthand for the
+ // `ParseResult.Type` issue Effect would otherwise build by hand.
return `JSON Schema validation failed: ${error}`;
}
if (validation.valid) {
diff --git a/ts/packages/json-schema-to-effect-schema/test/json-schema-to-effect-schema.test.ts b/ts/packages/json-schema-to-effect-schema/test/json-schema-to-effect-schema.test.ts
index 118b32203..5bc16e50e 100644
--- a/ts/packages/json-schema-to-effect-schema/test/json-schema-to-effect-schema.test.ts
+++ b/ts/packages/json-schema-to-effect-schema/test/json-schema-to-effect-schema.test.ts
@@ -141,3 +141,143 @@ describe('shared cross-SDK object corpus', () => {
});
}
});
+
+describe('schema defects fail at construction', () => {
+ // `@cfworker/json-schema` resolves references and compiles regexes inside
+ // `validate`, so each of these used to reach the caller once per call, as an
+ // input validation failure. The consumer wraps construction in its own
+ // `Effect.try` and reports a compile failure against the cached schema path,
+ // which is the accurate diagnosis for all of them.
+ const defects: ReadonlyArray<readonly [string, JsonSchema, RegExp]> = [
+ [
+ 'an invalid patternProperties regular expression',
+ { type: 'object', patternProperties: { '[': { type: 'string' } } },
+ /Invalid patternProperties regular expression/,
+ ],
+ [
+ 'an invalid patternProperties regular expression nested under a property',
+ {
+ type: 'object',
+ properties: { a: { type: 'object', patternProperties: { '(': { type: 'string' } } } },
+ },
+ /Invalid patternProperties regular expression/,
+ ],
+ [
+ 'an invalid patternProperties regular expression inside array items',
+ {
+ type: 'object',
+ properties: {
+ a: { type: 'array', items: { type: 'object', patternProperties: { '(?<': {} } } },
+ },
+ },
+ /Invalid patternProperties regular expression/,
+ ],
+ [
+ 'an unresolved local $ref in a patternProperties subschema',
+ { type: 'object', patternProperties: { '^s_': { $ref: '#/$defs/Missing' } } },
+ /Unresolved \$ref .* in a dynamic-key schema/,
+ ],
+ [
+ 'an external $ref in a patternProperties subschema',
+ { type: 'object', patternProperties: { '^s_': { $ref: 'https://example.com/s.json' } } },
+ /Unresolved \$ref .* in a dynamic-key schema/,
+ ],
+ [
+ 'an unresolved local $ref in a schema-valued additionalProperties',
+ { type: 'object', additionalProperties: { $ref: '#/$defs/Missing' } },
+ /Unresolved \$ref .* in a dynamic-key schema/,
+ ],
+ [
+ 'a dynamic-key reference whose target carries a dangling reference',
+ {
+ type: 'object',
+ additionalProperties: { $ref: '#/$defs/Hop' },
+ $defs: { Hop: { type: 'object', properties: { a: { $ref: '#/$defs/Missing' } } } },
+ },
+ /Unresolved \$ref .* in a dynamic-key schema/,
+ ],
+ [
+ 'a duplicate schema URI',
+ {
+ $id: 'https://example.com/a',
+ type: 'object',
+ $defs: { x: { $id: 'https://example.com/a', type: 'string' } },
+ },
+ /Duplicate schema URI/,
+ ],
+ ];
+
+ // Deliberately outside the scope above: matching the Python SDK, which only
+ // rejects dynamic-key schemas while wrapping a tool. Widening to every `$ref`
+ // would reject tool schemas whose dangling reference sits in a branch the
+ // interpreter never descends into, and which validate today.
+ const toleratedOutsideDynamicKeys: ReadonlyArray<readonly [string, JsonSchema]> = [
+ [
+ 'an unresolved $ref under a declared property',
+ { type: 'object', properties: { a: { $ref: '#/$defs/Missing' } } },
+ ],
+ [
+ 'an unresolved $ref inside array items',
+ { type: 'object', properties: { a: { type: 'array', items: { $ref: '#/$defs/Gone' } } } },
+ ],
+ [
+ 'an invalid pattern regular expression',
+ { type: 'object', properties: { a: { type: 'string', pattern: '[' } } },
+ ],
+ ];
+
+ for (const [label, schema] of toleratedOutsideDynamicKeys) {
+ it(`leaves ${label} to the interpreter`, () => {
+ expect(() => jsonSchemaToEffectSchema(schema)).not.toThrow();
+ });
+ }
+
+ for (const [label, schema, message] of defects) {
+ it(`rejects ${label}`, () => {
+ expect(() => jsonSchemaToEffectSchema(schema)).toThrow(message);
+ });
+ }
+
+ it('resolves a local $ref that does exist', () => {
+ const schema = {
+ type: 'object',
+ properties: { a: { $ref: '#/$defs/Name' } },
+ required: ['a'],
+ $defs: { Name: { type: 'string' } },
+ } satisfies JsonSchema;
+
+ expect(() => jsonSchemaToEffectSchema(schema)).not.toThrow();
+ expect(effectAccepts(schema, { a: 'Ada' })).toBe(true);
+ expect(effectAccepts(schema, { a: 1 })).toBe(false);
+ });
+
+ it('accepts a self-referential $ref without re-entering it', () => {
+ const schema = {
+ type: 'object',
+ properties: { next: { $ref: '#' } },
+ } satisfies JsonSchema;
+
+ expect(() => jsonSchemaToEffectSchema(schema)).not.toThrow();
+ expect(effectAccepts(schema, { next: { next: {} } })).toBe(true);
+ });
+});
+
+describe('input the interpreter cannot represent stays an input failure', () => {
+ // The one throw in `validate` that depends on the instance rather than the
+ // schema. It must stay inside the filter: throwing here would escape
+ // `Schema.decodeUnknown` as a defect instead of a typed parse error.
+ const unrepresentable: ReadonlyArray<readonly [string, unknown]> = [
+ ['a bigint', BigInt(1)],
+ ['a function', () => 1],
+ ['a symbol', Symbol('x')],
+ ['undefined', undefined],
+ ];
+
+ for (const [label, input] of unrepresentable) {
+ it(`rejects ${label} without throwing`, () => {
+ const schema = jsonSchemaToEffectSchema({ type: 'object' });
+ expect(() => Schema.decodeUnknownOption(schema)(input)).not.toThrow();
+ expect(Option.isSome(Schema.decodeUnknownOption(schema)(input))).toBe(false);
+ });
+ }
+});