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

next
ts 571 lines 19 KB
Raw
1 import { dereference, Validator } from '@cfworker/json-schema';
2 import type { OutputUnit, Schema as InterpreterSchema, SchemaDraft } from '@cfworker/json-schema';
3 import { Schema } from 'effect';
4
5 export type JsonSchemaValidationIssue = {
6 readonly code: string;
7 readonly keys?: ReadonlyArray<string>;
8 readonly message: string;
9 readonly path: ReadonlyArray<PropertyKey>;
10 };
11
12 export type JsonSchemaToEffectSchemaOptions = {
13 readonly draft?: SchemaDraft;
14 readonly formatIssues?: (
15 issues: ReadonlyArray<JsonSchemaValidationIssue>
16 ) => ReadonlyArray<string>;
17 };
18
19 type JsonObject = Record<string, unknown>;
20
21 const BASE64_PATTERN = '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$';
22
23 const schemaMapKeywords = new Set([
24 '$defs',
25 'definitions',
26 'dependentSchemas',
27 'patternProperties',
28 'properties',
29 ]);
30
31 const schemaArrayKeywords = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
32
33 const schemaValueKeywords = new Set([
34 'additionalItems',
35 'additionalProperties',
36 'contains',
37 'else',
38 'if',
39 'items',
40 'not',
41 'propertyNames',
42 'then',
43 'unevaluatedItems',
44 'unevaluatedProperties',
45 ]);
46
47 const isJsonObject = (value: unknown): value is JsonObject =>
48 typeof value === 'object' && value !== null && !Array.isArray(value);
49
50 const isObjectSchema = (schema: JsonObject): boolean =>
51 schema.type === 'object' ||
52 'properties' in schema ||
53 'patternProperties' in schema ||
54 'additionalProperties' in schema;
55
56 const hasNamedProperties = (schema: JsonObject): boolean =>
57 isJsonObject(schema.properties) && Object.keys(schema.properties).length > 0;
58
59 const isClosedObjectBranch = (branch: unknown): branch is JsonObject =>
60 isJsonObject(branch) &&
61 isObjectSchema(branch) &&
62 hasNamedProperties(branch) &&
63 branch.additionalProperties === undefined &&
64 branch.patternProperties === undefined &&
65 branch.$ref === undefined;
66
67 // Sibling `allOf` object branches must not reject each other's keys, so each
68 // closed branch is materialized open and the strictness a lone named-property
69 // object would have had is re-applied once, over the union of every branch's
70 // properties. Mirrors `parseAllOf` in @composio/json-schema-to-zod.
71 const openAllOfBranches = (source: JsonObject, normalized: JsonObject): void => {
72 const sourceBranches = source.allOf;
73 const branches = normalized.allOf;
74 if (!Array.isArray(sourceBranches) || !Array.isArray(branches) || branches.length < 2) {
75 return;
76 }
77
78 const closed = sourceBranches.map(isClosedObjectBranch);
79 if (!closed.some(Boolean)) {
80 return;
81 }
82
83 branches.forEach((branch, index) => {
84 if (closed[index] && isJsonObject(branch)) {
85 branch.additionalProperties = true;
86 }
87 });
88
89 if (
90 !closed.every(Boolean) ||
91 normalized.properties !== undefined ||
92 normalized.patternProperties !== undefined ||
93 normalized.additionalProperties !== undefined
94 ) {
95 return;
96 }
97
98 normalized.properties = Object.fromEntries(
99 sourceBranches.flatMap(branch =>
100 Object.keys((branch as JsonObject).properties as JsonObject).map(key => [key, true])
101 )
102 );
103 normalized.additionalProperties = false;
104 };
105
106 const appendAllOf = (schema: JsonObject, constraint: JsonObject): void => {
107 const current = schema.allOf;
108 schema.allOf = Array.isArray(current) ? [...current, constraint] : [constraint];
109 };
110
111 const normalizeBounds = (schema: JsonObject): void => {
112 const type = schema.type;
113 const minimum = schema.min;
114 const maximum = schema.max;
115
116 if (typeof minimum === 'number') {
117 if ((type === 'number' || type === 'integer') && schema.minimum === undefined) {
118 schema.minimum = minimum;
119 } else if (type === 'string' && schema.minLength === undefined) {
120 schema.minLength = minimum;
121 } else if (type === 'array' && schema.minItems === undefined) {
122 schema.minItems = minimum;
123 }
124 }
125
126 if (typeof maximum === 'number') {
127 if ((type === 'number' || type === 'integer') && schema.maximum === undefined) {
128 schema.maximum = maximum;
129 } else if (type === 'string' && schema.maxLength === undefined) {
130 schema.maxLength = maximum;
131 } else if (type === 'array' && schema.maxItems === undefined) {
132 schema.maxItems = maximum;
133 }
134 }
135 };
136
137 // OpenAPI 3.0 / JSON Schema draft-4 express exclusive bounds as a boolean flag
138 // on `minimum`/`maximum`. The Draft 7 interpreter expects numeric
139 // `exclusiveMinimum`/`exclusiveMaximum` and would silently ignore the flag,
140 // turning an exclusive bound into an inclusive one.
141 const normalizeExclusiveBounds = (schema: JsonObject): void => {
142 if (schema.exclusiveMinimum === true && typeof schema.minimum === 'number') {
143 schema.exclusiveMinimum = schema.minimum;
144 delete schema.minimum;
145 } else if (typeof schema.exclusiveMinimum === 'boolean') {
146 delete schema.exclusiveMinimum;
147 }
148
149 if (schema.exclusiveMaximum === true && typeof schema.maximum === 'number') {
150 schema.exclusiveMaximum = schema.maximum;
151 delete schema.maximum;
152 } else if (typeof schema.exclusiveMaximum === 'boolean') {
153 delete schema.exclusiveMaximum;
154 }
155 };
156
157 const normalizeFormats = (schema: JsonObject): void => {
158 if (schema.type === 'number' && schema.format === 'int64') {
159 schema.type = 'integer';
160 }
161
162 if (schema.type !== 'string') {
163 return;
164 }
165
166 // Mirrors parse-string.ts in @composio/json-schema-to-zod: only a base64
167 // `contentEncoding` is checked, case-insensitively (RFC 2045).
168 if (
169 typeof schema.contentEncoding === 'string' &&
170 schema.contentEncoding.toLowerCase() === 'base64'
171 ) {
172 if (schema.pattern === undefined) {
173 schema.pattern = BASE64_PATTERN;
174 } else {
175 appendAllOf(schema, { pattern: BASE64_PATTERN });
176 }
177 }
178
179 if (schema.format === 'ip') {
180 delete schema.format;
181 appendAllOf(schema, {
182 anyOf: [{ format: 'ipv4' }, { format: 'ipv6' }],
183 });
184 }
185 };
186
187 const normalizeNullable = (schema: JsonObject): JsonObject => {
188 if (schema.nullable !== true) {
189 return schema;
190 }
191
192 delete schema.nullable;
193 if (typeof schema.type === 'string') {
194 schema.type = [schema.type, 'null'];
195 return schema;
196 }
197 if (Array.isArray(schema.type)) {
198 schema.type = schema.type.includes('null') ? schema.type : [...schema.type, 'null'];
199 return schema;
200 }
201
202 return { anyOf: [schema, { type: 'null' }] };
203 };
204
205 const normalizeSchemaNode = (
206 value: unknown,
207 draft: SchemaDraft,
208 seen: WeakMap<object, InterpreterSchema | boolean>
209 ): InterpreterSchema | boolean => {
210 if (typeof value === 'boolean') {
211 return value;
212 }
213 if (!isJsonObject(value)) {
214 return true;
215 }
216
217 const existing = seen.get(value);
218 if (existing) {
219 return existing;
220 }
221
222 const normalized: JsonObject = {};
223 seen.set(value, normalized as InterpreterSchema);
224
225 for (const [key, child] of Object.entries(value)) {
226 if (schemaMapKeywords.has(key) && isJsonObject(child)) {
227 normalized[key] = Object.fromEntries(
228 Object.entries(child).map(([name, nested]) => [
229 name,
230 normalizeSchemaNode(nested, draft, seen),
231 ])
232 );
233 } else if (schemaArrayKeywords.has(key) && Array.isArray(child)) {
234 normalized[key] = child.map(nested => normalizeSchemaNode(nested, draft, seen));
235 } else if (schemaValueKeywords.has(key)) {
236 normalized[key] = Array.isArray(child)
237 ? child.map(nested => normalizeSchemaNode(nested, draft, seen))
238 : normalizeSchemaNode(child, draft, seen);
239 } else {
240 normalized[key] = child;
241 }
242 }
243
244 // Composio tool inputs treat an omitted `additionalProperties` as strict, but
245 // only for objects that actually name properties. Injecting `false` into a
246 // property-less object (`{ type: "object" }`, `properties: {}`) or a
247 // pattern-only object turned every valid free-form payload into an unknown-key
248 // rejection.
249 if (
250 isObjectSchema(normalized) &&
251 normalized.additionalProperties === undefined &&
252 hasNamedProperties(normalized)
253 ) {
254 normalized.additionalProperties = false;
255 }
256
257 openAllOfBranches(value, normalized);
258
259 normalizeBounds(normalized);
260 // Draft 4 is the dialect that defines the boolean spelling, and the
261 // interpreter honors it there; rewriting would hand it a numeric bound it
262 // ignores under that draft.
263 if (draft !== '4') {
264 normalizeExclusiveBounds(normalized);
265 }
266 normalizeFormats(normalized);
267 const withNullable = normalizeNullable(normalized);
268 seen.set(value, withNullable as InterpreterSchema);
269 return withNullable as InterpreterSchema;
270 };
271
272 const normalizeJsonSchema = (schema: JsonObject, draft: SchemaDraft): InterpreterSchema =>
273 normalizeSchemaNode(schema, draft, new WeakMap()) as InterpreterSchema;
274
275 // Walks the same child positions `normalizeSchemaNode` does, so a node is
276 // visited exactly where the interpreter would descend into it.
277 const forEachSchemaNode = (
278 value: unknown,
279 seen: WeakSet<object>,
280 visit: (node: JsonObject) => void
281 ): void => {
282 if (!isJsonObject(value) || seen.has(value)) {
283 return;
284 }
285 seen.add(value);
286 visit(value);
287
288 for (const [key, child] of Object.entries(value)) {
289 if (schemaMapKeywords.has(key) && isJsonObject(child)) {
290 for (const nested of Object.values(child)) {
291 forEachSchemaNode(nested, seen, visit);
292 }
293 } else if (schemaArrayKeywords.has(key) && Array.isArray(child)) {
294 for (const nested of child) {
295 forEachSchemaNode(nested, seen, visit);
296 }
297 } else if (schemaValueKeywords.has(key)) {
298 for (const nested of Array.isArray(child) ? child : [child]) {
299 forEachSchemaNode(nested, seen, visit);
300 }
301 }
302 }
303 };
304
305 const assertRegexCompiles = (pattern: string, keyword: string): void => {
306 try {
307 // The same flag `@cfworker/json-schema` compiles with, so this accepts
308 // exactly the patterns the interpreter would.
309 new RegExp(pattern, 'u');
310 } catch (cause) {
311 throw new Error(`Invalid ${keyword} regular expression ${JSON.stringify(pattern)}.`, { cause });
312 }
313 };
314
315 // Follows every reference reachable from one dynamic-key subschema, including
316 // through the schemas those references resolve to, so a local pointer whose
317 // target carries a dangling reference is caught as well.
318 const assertDynamicReferencesResolve = (
319 subSchema: unknown,
320 lookup: Record<string, unknown>,
321 seen: WeakSet<object>
322 ): void => {
323 forEachSchemaNode(subSchema, seen, node => {
324 const ref = node.$ref;
325 if (typeof ref !== 'string') {
326 return;
327 }
328
329 const absolute = (node as { readonly __absolute_ref__?: string }).__absolute_ref__ ?? ref;
330 const target = lookup[absolute];
331 if (target === undefined) {
332 throw new Error(`Unresolved $ref ${JSON.stringify(ref)} in a dynamic-key schema.`);
333 }
334
335 assertDynamicReferencesResolve(target, lookup, seen);
336 });
337 };
338
339 // `@cfworker/json-schema` compiles `patternProperties` keys and resolves `$ref`
340 // lazily, inside `validate`. Left alone, a defect in the schema surfaces once
341 // per call through the same channel as a genuine input failure, telling the
342 // caller their arguments are wrong when the tool's schema is what is broken.
343 // Checking eagerly moves those defects to construction, where the CLI already
344 // reports them as a compile failure against the cached schema path.
345 //
346 // The scope matches what the Python SDK rejects while wrapping a tool: the keys
347 // of `patternProperties`, and references inside a dynamic-key subschema. A
348 // reference in a declared property is deliberately left to the interpreter —
349 // widening past parity would reject tool schemas that validate today.
350 const assertSchemaIsInterpretable = (schema: InterpreterSchema): void => {
351 // Re-derives the lookup the `Validator` keeps private. `dereference` builds a
352 // fresh map per call and reuses the `__absolute_ref__` it already stamped, so
353 // running it a second time is consistent with the interpreter's own view.
354 const lookup = dereference(schema);
355
356 forEachSchemaNode(schema, new WeakSet(), node => {
357 const patternProperties = node.patternProperties;
358 if (isJsonObject(patternProperties)) {
359 for (const [pattern, patternSchema] of Object.entries(patternProperties)) {
360 assertRegexCompiles(pattern, 'patternProperties');
361 assertDynamicReferencesResolve(patternSchema, lookup, new WeakSet());
362 }
363 }
364
365 if (isJsonObject(node.additionalProperties)) {
366 assertDynamicReferencesResolve(node.additionalProperties, lookup, new WeakSet());
367 }
368 });
369 };
370
371 const decodePointer = (pointer: string): ReadonlyArray<string> => {
372 if (pointer === '#' || pointer === '') {
373 return [];
374 }
375
376 const fragment = pointer.startsWith('#') ? pointer.slice(1) : pointer;
377 return fragment
378 .split('/')
379 .slice(1)
380 .map(part => part.replace(/~1/g, '/').replace(/~0/g, '~'));
381 };
382
383 const encodePointerPart = (part: string): string => part.replace(/~/g, '~0').replace(/\//g, '~1');
384
385 const instancePath = (pointer: string): ReadonlyArray<PropertyKey> =>
386 decodePointer(pointer).map(part => (/^(?:0|[1-9]\d*)$/.test(part) ? Number(part) : part));
387
388 const valueAtPointer = (root: unknown, pointer: string): unknown =>
389 decodePointer(pointer).reduce<unknown>((current, part) => {
390 if (isJsonObject(current)) {
391 return current[part];
392 }
393 if (Array.isArray(current) && /^(?:0|[1-9]\d*)$/.test(part)) {
394 return current[Number(part)];
395 }
396 return undefined;
397 }, root);
398
399 const parentSchemaAtKeyword = (
400 schema: InterpreterSchema,
401 keywordLocation: string
402 ): JsonObject | null => {
403 const parts = decodePointer(keywordLocation);
404 const parentPointer = `#/${parts.slice(0, -1).map(encodePointerPart).join('/')}`;
405 const parent = valueAtPointer(schema, parts.length === 1 ? '#' : parentPointer);
406 return isJsonObject(parent) ? parent : null;
407 };
408
409 const propertyNameFromError = (error: OutputUnit): string | undefined =>
410 error.error.match(/^Property "([^"]+)"/)?.[1];
411
412 const requiredNameFromError = (error: OutputUnit): string | undefined =>
413 error.error.match(/required property "([^"]+)"/)?.[1];
414
415 const matchesPattern = (pattern: string, key: string): boolean => {
416 try {
417 return new RegExp(pattern, 'u').test(key);
418 } catch {
419 return false;
420 }
421 };
422
423 const propertyIsDeclared = (parent: JsonObject | null, key: string): boolean => {
424 if (!parent) {
425 return false;
426 }
427 if (isJsonObject(parent.properties) && key in parent.properties) {
428 return true;
429 }
430 if (!isJsonObject(parent.patternProperties)) {
431 return false;
432 }
433
434 return Object.keys(parent.patternProperties).some(pattern => matchesPattern(pattern, key));
435 };
436
437 const hasSpecificChildError = (errors: ReadonlyArray<OutputUnit>, error: OutputUnit): boolean =>
438 errors.some(
439 candidate =>
440 candidate !== error &&
441 candidate.instanceLocation.startsWith(`${error.instanceLocation}/`) &&
442 candidate.keyword !== 'additionalProperties'
443 );
444
445 const mapValidationErrors = (
446 errors: ReadonlyArray<OutputUnit>,
447 schema: InterpreterSchema
448 ): ReadonlyArray<JsonSchemaValidationIssue> => {
449 const ignored = new Set<OutputUnit>();
450 const unknownByLocation = new Map<string, Array<string>>();
451
452 for (const [index, error] of errors.entries()) {
453 if (error.keyword !== 'additionalProperties') {
454 continue;
455 }
456 const key = propertyNameFromError(error);
457 if (!key) {
458 continue;
459 }
460 const parent = parentSchemaAtKeyword(schema, error.keywordLocation);
461 const additionalProperties = valueAtPointer(schema, error.keywordLocation);
462 if (additionalProperties === false) {
463 const child = errors[index + 1];
464 const childLocation = `${error.instanceLocation}/${encodePointerPart(key)}`;
465 if (child?.keyword === 'false' && child.instanceLocation === childLocation) {
466 ignored.add(child);
467 }
468 }
469 if (propertyIsDeclared(parent, key)) {
470 ignored.add(error);
471 continue;
472 }
473
474 if (additionalProperties === false) {
475 const keys = unknownByLocation.get(error.instanceLocation) ?? [];
476 keys.push(key);
477 unknownByLocation.set(error.instanceLocation, keys);
478 ignored.add(error);
479 } else if (hasSpecificChildError(errors, error)) {
480 ignored.add(error);
481 }
482 }
483
484 const issues: Array<JsonSchemaValidationIssue> = [];
485 for (const [location, keys] of unknownByLocation) {
486 issues.push({
487 code: 'unrecognized_keys',
488 keys,
489 message: `Unknown key${keys.length === 1 ? '' : 's'}: ${keys.join(', ')}`,
490 path: instancePath(location),
491 });
492 }
493
494 for (const error of errors) {
495 if (ignored.has(error)) {
496 continue;
497 }
498 if (
499 (error.keyword === 'properties' ||
500 error.keyword === 'patternProperties' ||
501 error.keyword === '$ref') &&
502 hasSpecificChildError(errors, error)
503 ) {
504 continue;
505 }
506
507 const path = [...instancePath(error.instanceLocation)];
508 const requiredName = error.keyword === 'required' ? requiredNameFromError(error) : undefined;
509 if (requiredName) {
510 path.push(requiredName);
511 }
512 issues.push({ code: error.keyword, message: error.error, path });
513 }
514
515 return issues;
516 };
517
518 const defaultFormatIssues = (
519 issues: ReadonlyArray<JsonSchemaValidationIssue>
520 ): ReadonlyArray<string> =>
521 issues.map(issue => {
522 const location = issue.path.length > 0 ? issue.path.join('.') : '<root>';
523 return `${location}: ${issue.message}`;
524 });
525
526 // Validation is expressed as a filter over `Schema.Unknown` rather than a
527 // `Schema.declare` codec: the interpreter already owns the whole decision, so
528 // there is nothing to decode, and a filter reports every failure through the
529 // `{ path, issue }` shape Effect normalizes for us (`Schema.makeFilter`
530 // returns a `FilterOutput`; a string is the shorthand for a single
531 // `SchemaIssue.InvalidValue` carrying that message).
532 export const jsonSchemaToEffectSchema = (
533 jsonSchema: JsonObject,
534 options: JsonSchemaToEffectSchemaOptions = {}
535 ): Schema.Codec<unknown> => {
536 const draft = options.draft ?? '7';
537 const normalizedSchema = normalizeJsonSchema(jsonSchema, draft);
538 const validator = new Validator(normalizedSchema, draft, false);
539 assertSchemaIsInterpretable(normalizedSchema);
540 const formatIssues = options.formatIssues ?? defaultFormatIssues;
541
542 return Schema.Unknown.check(
543 Schema.makeFilter((input): Schema.FilterOutput => {
544 let validation: ReturnType<Validator['validate']>;
545 try {
546 validation = validator.validate(input);
547 } catch (error) {
548 // Schema defects are rejected at construction, so what reaches here is
549 // input the interpreter cannot represent at all — a `bigint`, `symbol`,
550 // `function`, or `undefined`. That is a property of the input, so it
551 // belongs in the filter. A string is the filter's shorthand for the
552 // `SchemaIssue.InvalidValue` issue Effect would otherwise build by hand.
553 return `JSON Schema validation failed: ${error}`;
554 }
555 if (validation.valid) {
556 return true;
557 }
558
559 const issues = mapValidationErrors(validation.errors, normalizedSchema);
560 const messages = formatIssues(issues);
561 if (messages.length === 0) {
562 return 'Input does not match the JSON schema.';
563 }
564
565 // `formatIssues` may fan one issue out into several messages, so the
566 // location stays inside the message (as it always has) instead of being
567 // reported as a structural path.
568 return messages.map(message => ({ path: [], issue: message }));
569 })
570 );
571 };