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
import { z } from 'zod/v3';
import { JsonSchemaRefResolutionError, JsonSchemaToZodError } from '../errors';
import { jsonSchemaToZod } from '@composio/json-schema-to-zod';
import logger from './logger';
import { isPlainObject } from './modifiers/FileToolModifier.utils.neutral';
const MAX_REF_CHAIN_DEPTH = 100;
const MAX_NODE_DEPTH = 512;
const CYCLE_BREAK_SENTINEL = { type: 'object', additionalProperties: true } as const;
/** Keywords whose value is a single subschema. */
const SCHEMA_KEYWORDS = new Set([
'additionalItems',
'additionalProperties',
'contains',
'contentSchema',
'else',
'if',
'not',
'propertyNames',
'then',
'unevaluatedItems',
'unevaluatedProperties',
]);
/** Keywords whose value is an array of subschemas. */
const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
/** Keywords whose value is a map from name to subschema. */
const SCHEMA_MAP_KEYWORDS = new Set([
'$defs',
'definitions',
'dependentSchemas',
'patternProperties',
'properties',
]);
/** Keywords whose values are instance data, never subschemas. */
const INSTANCE_VALUE_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
/**
* In-band hint attached to the cycle-break sentinel when lenient mode
* substitutes it for a dangling `$ref`. Makes the degradation visible to
* LLMs that read the wrapped tool's schema — without it the LLM sees a
* useless permissive object and no prose context. Wording is intentionally
* context-neutral ("Schema shape", not "Output shape") because the helper
* is used for both `inputParameters` and `outputParameters`. Overridden
* when the caller's `$ref` node carries its own `description` sibling
* (Draft 2020-12 sibling-keyword semantics).
*/
const UNRESOLVED_REF_DESCRIPTION =
'Schema shape unresolved at the source — validate loosely. ' +
'See https://github.com/ComposioHQ/composio/issues/3307.';
/**
* Strategy for `dereferenceJsonSchema` when an internal `$ref` cannot be
* resolved (target missing under `$defs`/`definitions`, or a malformed
* pointer beneath the internal `#/` prefix).
*
* - `'throw'` (default): throw `JsonSchemaRefResolutionError`. Right for
* first-party / custom-tool schemas where a dangling `$ref` is a developer
* bug worth surfacing.
* - `'sentinel'`: replace the offending node with the cycle-break sentinel
* (`{ type: 'object', additionalProperties: true }`). Right for schemas
* sourced from an upstream service the caller cannot edit (e.g. an
* API-provided tool definition that emits `$ref` without a `$defs`
* block — see https://github.com/ComposioHQ/composio/issues/3307).
*
* Safety caps (`MAX_REF_CHAIN_DEPTH`, `MAX_NODE_DEPTH`) still throw in both
* modes; cycle handling (already permissive via `CYCLE_BREAK_SENTINEL`) is
* unaffected.
*/
export type UnresolvedRefStrategy = 'throw' | 'sentinel';
/**
* Reason a `$ref` was replaced with the sentinel in `'sentinel'` mode.
* `onReplace` callbacks receive this so callers can attribute the
* fallback (e.g., warn at the offending tool slug).
*/
export type UnresolvedRefReason = 'missing-target' | 'malformed-pointer';
export interface DereferenceJsonSchemaOptions {
onUnresolved?: UnresolvedRefStrategy;
/**
* Invoked once per replaced node in `'sentinel'` mode. The ref is the
* original pointer string from the schema; reason distinguishes a
* missing `$defs` target from a malformed pointer.
*/
onReplace?: (ref: string, reason: UnresolvedRefReason) => void;
}
const POLLUTING_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
const REF_RESOLUTION_FIXES = [
'Ensure the $ref pointer matches a path in $defs or definitions',
'External $ref pointers (http://, https://, file://, …) are not resolved by the SDK',
];
const decodePointerSegment = (segment: string): string =>
segment.replace(/~1/g, '/').replace(/~0/g, '~');
/**
* Tagged result of attempting to resolve a `$ref`. `failedAt` is populated
* only for the segment-walk path so strict-mode error meta stays identical
* to the pre-lenient-mode shape.
*/
type ResolutionResult =
| { kind: 'ok'; value: unknown }
| { kind: 'unresolved'; reason: UnresolvedRefReason; failedAt?: string };
const tryStep = (cursor: unknown, segment: string): ResolutionResult => {
if (cursor === null || typeof cursor !== 'object') {
return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
}
if (Array.isArray(cursor)) {
const i = Number(segment);
if (!Number.isInteger(i) || i < 0 || i >= cursor.length) {
return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
}
return { kind: 'ok', value: cursor[i] };
}
const obj = cursor as Record<string, unknown>;
if (!Object.prototype.hasOwnProperty.call(obj, segment)) {
return { kind: 'unresolved', reason: 'missing-target', failedAt: segment };
}
return { kind: 'ok', value: obj[segment] };
};
const tryResolvePointer = (root: Record<string, unknown>, pointer: string): ResolutionResult => {
if (pointer === '#' || pointer === '') return { kind: 'ok', value: root };
if (!pointer.startsWith('#/')) {
return { kind: 'unresolved', reason: 'malformed-pointer' };
}
const segments = pointer.slice(2).split('/').map(decodePointerSegment);
let cursor: unknown = root;
for (const seg of segments) {
const step = tryStep(cursor, seg);
if (step.kind === 'unresolved') return step;
cursor = step.value;
}
return { kind: 'ok', value: cursor };
};
const throwResolutionError = (
pointer: string,
result: Extract<ResolutionResult, { kind: 'unresolved' }>
): never => {
if (result.reason === 'malformed-pointer') {
throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
meta: { ref: pointer },
possibleFixes: REF_RESOLUTION_FIXES,
});
}
throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
meta: {
ref: pointer,
...(result.failedAt !== undefined ? { failedAt: result.failedAt } : {}),
},
possibleFixes: REF_RESOLUTION_FIXES,
});
};
/**
* Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and legacy
* `#/definitions/...`) so the returned schema can be safely handed to
* consumers that don't tolerate unresolved references (e.g. AJV in
* `@mastra/schema-compat`). External (`http://`, `https://`, …) refs are
* left untouched. Cycles are broken with `{ type: 'object',
* additionalProperties: true }`. The input is never mutated.
*
* By default, unresolved internal refs throw `JsonSchemaRefResolutionError`.
* Pass `{ onUnresolved: 'sentinel' }` to replace the offending node with the
* cycle-break sentinel instead — appropriate for schemas sourced from an
* upstream service the caller cannot edit (the Composio API ships some
* `outputParameters` with a `$ref` into `#/$defs/...` but never declares
* `$defs`; see https://github.com/ComposioHQ/composio/issues/3307).
*
* @throws {JsonSchemaRefResolutionError} on malformed pointers, missing
* targets (strict mode only), or chains past the depth cap (both modes).
*/
export function dereferenceJsonSchema<T = unknown>(
schema: T,
options?: DereferenceJsonSchemaOptions
): T {
if (!isPlainObject(schema)) return schema;
const strategy: UnresolvedRefStrategy = options?.onUnresolved ?? 'throw';
const onReplace = options?.onReplace;
const root = schema as Record<string, unknown>;
const visiting = new WeakSet<object>();
// POLLUTING_KEYS filter prevents an attacker-shaped $defs entry from altering
// the cloned node's prototype.
const cloneChildren = (
obj: Record<string, unknown>,
visitedRefs: ReadonlySet<string>,
chainDepth: number,
nodeDepth: number
): Record<string, unknown> =>
Object.fromEntries(
Object.entries(obj)
.filter(([k]) => !POLLUTING_KEYS.has(k))
.map(([k, v]) => [k, walk(v, visitedRefs, chainDepth, nodeDepth + 1)])
);
// `function` (not `const`) so `cloneChildren` above can call it via hoisting.
function walk(
node: unknown,
visitedRefs: ReadonlySet<string>,
chainDepth: number,
nodeDepth: number
): unknown {
if (nodeDepth >= MAX_NODE_DEPTH) {
throw new JsonSchemaRefResolutionError(
`JSON Schema node depth exceeded cap (${MAX_NODE_DEPTH})`,
{ possibleFixes: REF_RESOLUTION_FIXES }
);
}
if (Array.isArray(node)) {
if (visiting.has(node)) return { ...CYCLE_BREAK_SENTINEL };
visiting.add(node);
try {
return node.map(item => walk(item, visitedRefs, chainDepth, nodeDepth + 1));
} finally {
visiting.delete(node);
}
}
if (!isPlainObject(node)) return node;
if (visiting.has(node)) return { ...CYCLE_BREAK_SENTINEL };
visiting.add(node);
try {
const ref = typeof node.$ref === 'string' ? node.$ref : null;
// External refs and non-$ref nodes both pass through the same clone path.
if (ref === null || !ref.startsWith('#')) {
if (ref !== null) {
// Audit signal for security-sensitive deployments: a downstream
// resolver may fetch this and trigger SSRF or local-file disclosure.
logger.warn(`Leaving external $ref untouched: ${ref}`);
}
return cloneChildren(node, visitedRefs, chainDepth, nodeDepth);
}
if (chainDepth >= MAX_REF_CHAIN_DEPTH) {
throw new JsonSchemaRefResolutionError(
`JSON Schema $ref chain exceeded depth cap (${MAX_REF_CHAIN_DEPTH}): ${ref}`,
{ meta: { ref }, possibleFixes: REF_RESOLUTION_FIXES }
);
}
if (visitedRefs.has(ref)) return { ...CYCLE_BREAK_SENTINEL };
const result = tryResolvePointer(root, ref);
let target: unknown;
if (result.kind === 'ok') {
target = result.value;
} else if (strategy === 'sentinel') {
// Lenient mode: replace the unresolved branch with the same
// permissive sentinel used for cycles, and notify the caller so
// they can emit a one-shot warn at the offending tool surface.
// The injected `description` gives the LLM an in-band signal that
// the branch is opaque; sibling-merge below will overwrite it with
// a caller-provided description if the original node has one.
onReplace?.(ref, result.reason);
target = { ...CYCLE_BREAK_SENTINEL, description: UNRESOLVED_REF_DESCRIPTION };
} else {
throwResolutionError(ref, result);
}
const nextRefs = new Set(visitedRefs).add(ref);
const resolved = walk(target, nextRefs, chainDepth + 1, nodeDepth + 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 siblings: Record<string, unknown> = { ...node };
delete siblings.$ref;
if (Object.keys(siblings).length === 0 || !isPlainObject(resolved)) {
return resolved;
}
return { ...resolved, ...cloneChildren(siblings, visitedRefs, chainDepth, nodeDepth) };
} finally {
visiting.delete(node);
}
}
const out = walk(root, new Set(), 0, 0);
if (isPlainObject(out)) {
delete out.$defs;
delete out.definitions;
}
return out as T;
}
/**
* Returns a deep-cloned JSON Schema in which every node that carries a
* `properties` keyword also carries `type: "object"` when it has no explicit
* `type`. OpenAI tolerates the omission, but Google Gemini enforces OpenAPI
* 3.0 strictly and rejects function declarations whose nested objects are
* missing the `type` (see https://github.com/ComposioHQ/composio/issues/4022).
*
* The function follows JSON Schema's schema-bearing keywords while keeping
* property maps and instance values as containers. Nodes that already declare
* a `type` are left untouched.
*/
export function ensureObjectTypeOnProperties<T = unknown>(schema: T): T {
type WalkMode = 'schema' | 'schema-array' | 'schema-map' | 'dependencies-map' | 'value';
function walk(value: unknown, mode: WalkMode, depth = 0): unknown {
if (depth > MAX_NODE_DEPTH) {
throw new RangeError(`JSON Schema exceeds maximum nesting depth of ${MAX_NODE_DEPTH}`);
}
if (Array.isArray(value)) {
const itemMode = mode === 'schema-array' ? 'schema' : 'value';
return value.map(item => walk(item, itemMode, depth + 1));
}
if (!isPlainObject(value)) return value;
const clone: Record<string, unknown> = {};
for (const [key, child] of Object.entries(value)) {
let childMode: WalkMode = 'value';
if (mode === 'schema-map') {
childMode = 'schema';
} else if (mode === 'dependencies-map') {
childMode = Array.isArray(child) ? 'value' : 'schema';
} else if (mode === 'schema') {
if (SCHEMA_MAP_KEYWORDS.has(key)) {
childMode = 'schema-map';
} else if (SCHEMA_ARRAY_KEYWORDS.has(key) || (key === 'items' && Array.isArray(child))) {
childMode = 'schema-array';
} else if (SCHEMA_KEYWORDS.has(key) || key === 'items') {
childMode = 'schema';
} else if (key === 'dependencies') {
childMode = 'dependencies-map';
}
}
Object.defineProperty(clone, key, {
configurable: true,
enumerable: true,
value: walk(child, childMode, depth + 1),
writable: true,
});
}
if (mode === 'schema' && clone.properties !== undefined && clone.type === undefined) {
clone.type = 'object';
}
return clone;
}
return walk(schema, 'schema') as T;
}
/**
* Returns a deep-cloned JSON Schema whose `required` arrays contain each entry
* at most once. Duplicate entries are invalid in JSON Schema 2020-12 but do
* not change the schema's meaning, so preserving the first occurrence is safe.
*
* Tool schemas originate both from the Composio API and direct provider calls.
* Keeping this normalization provider-agnostic lets every SDK provider receive
* canonical API schemas, while providers that further transform a schema can
* reapply it at their own emission boundary.
*/
export function deduplicateJsonSchemaRequiredArrays<T = unknown>(schema: T): T {
const seenSchemaValues = new WeakMap<object, unknown>();
const seenInstanceValues = new WeakMap<object, unknown>();
function walk(value: unknown, isSchema: boolean, depth = 0): unknown {
if (depth > MAX_NODE_DEPTH) {
throw new RangeError(`JSON Schema exceeds maximum nesting depth of ${MAX_NODE_DEPTH}`);
}
const seen = isSchema ? seenSchemaValues : seenInstanceValues;
if (Array.isArray(value)) {
const existing = seen.get(value);
if (existing) return existing;
const clone: unknown[] = [];
seen.set(value, clone);
for (const item of value) {
clone.push(walk(item, isSchema, depth + 1));
}
return clone;
}
if (!isPlainObject(value)) return value;
const existing = seen.get(value);
if (existing) return existing;
const clone: Record<string, unknown> = {};
seen.set(value, clone);
for (const [key, child] of Object.entries(value)) {
Object.defineProperty(clone, key, {
configurable: true,
enumerable: true,
value:
isSchema && key === 'required' && Array.isArray(child)
? [...new Set(walk(child, false, depth + 1) as unknown[])]
: walk(child, isSchema && !INSTANCE_VALUE_KEYWORDS.has(key), depth + 1),
writable: true,
});
}
return clone;
}
return walk(schema, true) as T;
}
/**
* Removes all non-required properties from the schema
*
* if no items are required, the schema is returned as is
* @param schema - The JSON schema to remove non-required properties from
* @returns The JSON schema with all non-required properties removed
*/
export const removeNonRequiredProperties = <
T extends {
type: 'object';
properties: Record<string, unknown>;
required?: string[];
additionalProperties?: unknown;
},
>(
schema: T
): T => {
if (schema && schema.type === 'object' && (schema.required as string[])?.length) {
schema.properties = Object.fromEntries(
Object.entries(schema.properties || {}).filter(([key]) =>
(schema.required as string[]).includes(key)
)
);
}
// In strict mode, we don't allow additional properties
schema.additionalProperties = false;
return schema as T;
};
/**
* Convert a JSON schema to a Zod schema
* @param jsonSchema - The JSON schema to convert
* @param strict - Eliminates all non-required properties from the schema
* @returns The Zod schema
*
* @throws {JsonSchemaToZodError} If the JSON schema is invalid
*
* @example
* ```ts
* const zodSchema = jsonSchemaToZodSchema({
* type: 'object',
* properties: {
* name: { type: 'string' },
* },
* });
*
* console.log(zodSchema);
* ```
*
* @example
* ```ts
* const zodSchema = jsonSchemaToZodSchema({
* type: 'object',
* properties: {
* name: { type: 'string' },
* age: { type: 'number' },
* },
* required: ['name'],
* }, { strict: true });
*
* console.log(zodSchema);
*
* // Output:
* // z.object({
* // name: z.string(),
* // })
* ```
*/
export function jsonSchemaToZodSchema<T extends z.ZodTypeAny>(
jsonSchema: Record<string, unknown>,
{ strict }: { strict?: boolean } = {
strict: false,
}
): T {
try {
let schema = jsonSchema;
// Remove all non-required properties from the schema if strict is true
if (strict && schema) {
schema = removeNonRequiredProperties(
schema as {
type: 'object';
properties: Record<string, unknown>;
required?: string[] | undefined;
}
);
}
// Convert the JSON schema properties to Zod schema
const zodSchema = jsonSchemaToZod(schema) as T;
return zodSchema;
} catch (error) {
// The cause names the offending property path; surface it in the message
// so a single malformed property is identifiable without unwrapping.
const detail = error instanceof Error ? `: ${error.message}` : '';
throw new JsonSchemaToZodError(`Failed to convert JSON Schema to Zod Schema${detail}`, {
cause: error,
});
}
}
/**
* Reason recorded when strict normalization rewrites a schema node. Every
* rewrite is lossless: the model can still express the same values.
*
* - `optional-property-nullable` — a property missing from `required` was
* added to it and widened to accept `null`, the emulation of optional
* fields that OpenAI structured outputs document.
* - `unsupported-keyword-stripped` — an annotation keyword the API rejects
* (`default`, `examples`) was removed.
* - `one-of-converted` — `oneOf` (unsupported) became `anyOf`.
*/
export type StrictSchemaChangeReason =
'optional-property-nullable' | 'unsupported-keyword-stripped' | 'one-of-converted';
/** A single lossless rewrite applied by {@link toStrictJsonSchema}. */
export interface StrictSchemaChange {
/** Path to the changed node relative to the root, e.g. `properties.cfg.items`. */
path: string;
reason: StrictSchemaChangeReason;
/** Human-readable detail about what specifically changed. */
detail?: string;
}
/**
* A schema construct strict structured outputs cannot express. Rewriting it
* would change what the tool accepts, so it is reported instead; providers
* send such a tool without strict mode.
*/
export interface StrictSchemaIncompatibility {
/** Path to the offending node relative to the root. */
path: string;
/** The keyword (or `$ref`) that has no strict-mode equivalent. */
keyword: string;
detail: string;
}
/** Result of {@link toStrictJsonSchema}. */
export interface StrictJsonSchemaResult {
/**
* The strict schema. Only usable when `unsupported` is empty; otherwise it
* is best-effort and the original schema should be sent without strict mode.
*/
schema: Record<string, unknown>;
/**
* The input schema the rewrite was computed from. Optionality is decided
* against this schema, so it is what `omitNullToolArguments` needs.
*/
source: Record<string, unknown>;
/** Lossless rewrites, capped at 50 entries; see `totalChanges`. */
changes: StrictSchemaChange[];
totalChanges: number;
/** Constructs strict mode cannot express. Non-empty means "do not use `schema`". */
unsupported: StrictSchemaIncompatibility[];
}
const MAX_STRICT_CHANGES = 50;
/** Annotation-only keywords OpenAI structured outputs rejects; safe to strip. */
const STRICT_STRIP_KEYWORDS = new Set(['examples', 'default']);
/** Keywords OpenAI structured outputs reject and that have no lossless rewrite. */
const STRICT_UNSUPPORTED_KEYWORDS = [
'allOf',
'prefixItems',
'additionalItems',
'contains',
'dependencies',
'dependentSchemas',
'else',
'if',
'not',
'propertyNames',
'then',
'unevaluatedItems',
'unevaluatedProperties',
];
/** Whether a `type` value declares exactly the object type. */
const isObjectType = (type: unknown): boolean =>
type === 'object' || (Array.isArray(type) && type.length === 1 && type[0] === 'object');
type StrictWalkMode = 'schema' | 'schema-array' | 'schema-map' | 'value';
const joinPath = (parent: string, key: string): string => (parent ? `${parent}.${key}` : key);
/**
* Sets an own property regardless of its name: a plain assignment to a key
* such as `__proto__` would set the prototype instead of storing the value.
*/
function setOwn(target: Record<string, unknown>, key: string, value: unknown): void {
Object.defineProperty(target, key, {
configurable: true,
enumerable: true,
value,
writable: true,
});
}
/**
* Widens a property schema so that `null` is an accepted value, without
* placing `type` beside `anyOf` (the API rejects that combination).
*/
function widenToNullable(node: Record<string, unknown>): Record<string, unknown> {
if (Array.isArray(node.anyOf)) {
const alreadyNullable = node.anyOf.some(
branch => isPlainObject(branch) && branch.type === 'null'
);
return alreadyNullable ? node : { ...node, anyOf: [...node.anyOf, { type: 'null' }] };
}
if (typeof node.type === 'string') {
return node.type === 'null' ? node : { ...node, type: [node.type, 'null'] };
}
if (Array.isArray(node.type)) {
return node.type.includes('null') ? node : { ...node, type: [...node.type, 'null'] };
}
if ((Array.isArray(node.enum) && node.enum.includes(null)) || node.const === null) return node;
// No `type` at all: an empty schema already accepts null; anything else
// (enum-only, const, composition) is wrapped so the annotation stays outside.
const { description, title, ...rest } = node;
if (Object.keys(rest).length === 0) return node;
return {
...(description !== undefined ? { description } : {}),
...(title !== undefined ? { title } : {}),
anyOf: [rest, { type: 'null' }],
};
}
/**
* Follows local `$ref` pointers from `node` until a concrete schema node is
* reached. Unresolvable or over-long chains return the last node seen.
*/
function resolveLocalRefs(node: unknown, root: Record<string, unknown>): unknown {
let current = node;
for (let hops = 0; hops < MAX_REF_CHAIN_DEPTH; hops++) {
if (!isPlainObject(current) || typeof current.$ref !== 'string') return current;
const resolution = tryResolvePointer(root, current.$ref);
if (resolution.kind === 'unresolved') return current;
current = resolution.value;
}
return current;
}
/** Whether a schema node accepts `null` as an instance. */
function schemaAcceptsNull(schema: unknown, root: Record<string, unknown>): boolean {
const node = resolveLocalRefs(schema, root);
if (!isPlainObject(node)) return true;
if (typeof node.type === 'string') return node.type === 'null';
if (Array.isArray(node.type)) return node.type.includes('null');
if (Array.isArray(node.enum)) return node.enum.includes(null);
if ('const' in node) return node.const === null;
for (const keyword of ['anyOf', 'oneOf']) {
const branches = node[keyword];
if (Array.isArray(branches)) return branches.some(branch => schemaAcceptsNull(branch, root));
}
return true;
}
/**
* Normalizes a tool parameter schema for OpenAI structured outputs
* (`strict: true`) at every depth, following the contract OpenAI documents:
*
* - every object lists all of its properties in `required` and sets
* `additionalProperties: false`;
* - properties that were optional stay available and are widened to accept
* `null` (`type: ['string', 'null']`, or an extra `anyOf` branch) — the
* documented way to emulate optional fields. Nothing is dropped, so the
* model keeps every parameter it could pass before. A `null` the model
* sends for such a property means "omitted"; the strict providers drop it
* before executing the tool (see {@link omitNullToolArguments});
* - `type` arrays are kept as-is (the API accepts them); `oneOf` becomes
* `anyOf`; `default` and `examples` are stripped;
* - local `$ref`s into `$defs`/`definitions` are kept (the API supports
* them, including recursion) and the definitions themselves are
* normalized; an optional `$ref` property is widened with an `anyOf`
* null branch;
* - constructs strict mode cannot express — objects that accept arbitrary
* keys (schema-valued or `true` `additionalProperties`, `patternProperties`,
* property-less free-form objects), boolean subschemas, `allOf`,
* `prefixItems`, tuple-form `items`, conditional and dependency keywords,
* external or dangling `$ref`s, and a non-object root — are reported in
* `unsupported` rather than rewritten into something narrower. Callers send
* such a tool without strict mode.
*
* The input is never mutated. Every rewrite is recorded in `changes` (capped
* at 50 entries; `totalChanges` carries the real count), and `required`
* arrays are de-duplicated at the end.
*/
export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
const changes: StrictSchemaChange[] = [];
const unsupported: StrictSchemaIncompatibility[] = [];
let totalChanges = 0;
const recordChange = (change: StrictSchemaChange): void => {
totalChanges += 1;
if (changes.length < MAX_STRICT_CHANGES) changes.push(change);
};
const root: Record<string, unknown> = isPlainObject(schema) ? schema : {};
function walkChildren(
node: Record<string, unknown>,
mode: StrictWalkMode,
depth: number,
path: string
): Record<string, unknown> {
const clone: Record<string, unknown> = {};
for (const [key, child] of Object.entries(node)) {
let childMode: StrictWalkMode = 'value';
if (mode === 'schema-map') {
childMode = 'schema';
} else if (mode === 'schema' && !INSTANCE_VALUE_KEYWORDS.has(key)) {
if (SCHEMA_MAP_KEYWORDS.has(key)) {
childMode = 'schema-map';
} else if (SCHEMA_ARRAY_KEYWORDS.has(key) || (key === 'items' && Array.isArray(child))) {
childMode = 'schema-array';
} else if (SCHEMA_KEYWORDS.has(key) || key === 'items') {
childMode = 'schema';
}
}
if (childMode === 'schema-map' && isPlainObject(child)) {
const mapClone: Record<string, unknown> = {};
for (const [name, subSchema] of Object.entries(child)) {
setOwn(
mapClone,
name,
walk(subSchema, 'schema', depth + 1, joinPath(joinPath(path, key), name))
);
}
setOwn(clone, key, mapClone);
continue;
}
setOwn(clone, key, walk(child, childMode, depth + 1, joinPath(path, key)));
}
return clone;
}
function walk(value: unknown, mode: StrictWalkMode, depth: number, path: string): unknown {
if (depth > MAX_NODE_DEPTH) {
throw new RangeError(`JSON Schema exceeds maximum nesting depth of ${MAX_NODE_DEPTH}`);
}
if (Array.isArray(value)) {
const itemMode = mode === 'schema-array' ? 'schema' : 'value';
return value.map((item, index) => walk(item, itemMode, depth + 1, `${path}[${index}]`));
}
if (!isPlainObject(value) || mode === 'value') return value;
const node: Record<string, unknown> = {};
for (const [key, child] of Object.entries(value)) {
if (STRICT_STRIP_KEYWORDS.has(key)) {
recordChange({
path,
reason: 'unsupported-keyword-stripped',
detail: `keyword "${key}" removed`,
});
continue;
}
setOwn(node, key, child);
}
if (Array.isArray(node.oneOf) && node.anyOf === undefined) {
node.anyOf = node.oneOf;
delete node.oneOf;
recordChange({ path, reason: 'one-of-converted', detail: 'oneOf became anyOf' });
}
for (const keyword of STRICT_UNSUPPORTED_KEYWORDS) {
if (node[keyword] !== undefined) {
unsupported.push({
path,
keyword,
detail: `"${keyword}" has no strict-mode equivalent`,
});
}
}
if (node.oneOf !== undefined) {
unsupported.push({ path, keyword: 'oneOf', detail: 'oneOf beside anyOf cannot be merged' });
}
if (Array.isArray(node.items)) {
unsupported.push({
path,
keyword: 'items',
detail: 'tuple-form items has no strict-mode equivalent',
});
} else if (typeof node.items === 'boolean') {
unsupported.push({ path, keyword: 'items', detail: 'boolean subschema' });
}
if (node.properties !== undefined && !isPlainObject(node.properties)) {
unsupported.push({ path, keyword: 'properties', detail: 'properties is not an object' });
}
const out = walkChildren(node, mode, depth, path);
if (typeof node.$ref === 'string') {
const resolution =
node.$ref === '#' || node.$ref.startsWith('#/')
? tryResolvePointer(root, node.$ref)
: ({ kind: 'unresolved', reason: 'malformed-pointer' } as const);
if (resolution.kind === 'unresolved') {
unsupported.push({
path,
keyword: '$ref',
detail: `unresolved $ref "${node.$ref}"`,
});
}
// The referenced definition is normalized where it is declared.
return out;
}
const declaresObjectType =
out.type === 'object' || (Array.isArray(out.type) && out.type.includes('object'));
if (!declaresObjectType && !isPlainObject(out.properties)) return out;
if (out.properties !== undefined && !isPlainObject(out.properties)) return out;
const properties: Record<string, unknown> = {};
if (isPlainObject(out.properties)) {
for (const [name, propertySchema] of Object.entries(out.properties)) {
setOwn(properties, name, propertySchema);
}
}
const declaredRequired = new Set(
Array.isArray(out.required) ? out.required.filter(entry => typeof entry === 'string') : []
);
for (const [name, propertySchema] of Object.entries(properties)) {
if (typeof propertySchema === 'boolean') {
unsupported.push({
path: joinPath(path, `properties.${name}`),
keyword: 'properties',
detail: 'boolean subschema',
});
continue;
}
if (declaredRequired.has(name) || !isPlainObject(propertySchema)) continue;
setOwn(properties, name, widenToNullable(propertySchema));
recordChange({
path: joinPath(path, `properties.${name}`),
reason: 'optional-property-nullable',
detail: `property "${name}" is now required and accepts null`,
});
}
const acceptsDynamicKeys =
out.additionalProperties === true || isPlainObject(out.additionalProperties);
if (acceptsDynamicKeys) {
unsupported.push({
path,
keyword: 'additionalProperties',
detail: 'object accepts arbitrary keys',
});
} else if (out.patternProperties !== undefined) {
unsupported.push({
path,
keyword: 'patternProperties',
detail: 'object accepts pattern-matched keys',
});
} else if (Object.keys(properties).length === 0 && out.additionalProperties === undefined) {
unsupported.push({
path,
keyword: 'properties',
detail: 'free-form object accepts arbitrary keys',
});
}
return {
...out,
...(out.type === undefined ? { type: 'object' } : {}),
properties,
required: Object.keys(properties),
...(acceptsDynamicKeys ? {} : { additionalProperties: false }),
};
}
const normalized = walk(root, 'schema', 0, '');
if (!isPlainObject(normalized) || !isObjectType(normalized.type)) {
unsupported.push({
path: '',
keyword: 'type',
detail: 'root must be a non-nullable object',
});
}
return {
schema: deduplicateJsonSchemaRequiredArrays(normalized) as Record<string, unknown>,
source: root,
changes,
totalChanges,
unsupported,
};
}
/**
* Drops `null`-valued arguments that the tool's own schema does not accept,
* recursively through nested objects and arrays.
*
* Strict structured outputs cannot express optional parameters, so
* {@link toStrictJsonSchema} makes every parameter required and nullable. The
* model then sends `null` for a parameter it would otherwise have omitted;
* forwarding that `null` to the tool would fail validation against the tool's
* real schema, so it is treated as "omitted". A `null` the original schema
* accepts (a nullable field, an explicit "clear this value") is kept.
*
* @param args - Normalized tool arguments.
* @param schema - The dereferenced tool parameter schema the arguments were
* produced for (`StrictJsonSchemaResult.source`).
* @returns A new object; the input is not mutated.
*/
export function omitNullToolArguments(
args: Record<string, unknown>,
schema: unknown
): Record<string, unknown> {
const root: Record<string, unknown> = isPlainObject(schema) ? schema : {};
return omitNulls(args, root, root, 0) as Record<string, unknown>;
}
/**
* Picks the composition branch that describes a value's shape: the first
* branch with `properties` for an object, the first with `items` for an
* array. Nodes without a composition are returned as they are.
*/
function selectBranchFor(
schema: unknown,
value: unknown,
root: Record<string, unknown>
): Record<string, unknown> | undefined {
const resolved = resolveLocalRefs(schema, root);
if (!isPlainObject(resolved)) return undefined;
const wanted = Array.isArray(value) ? 'items' : 'properties';
const find = (node: unknown, depth: number): Record<string, unknown> | undefined => {
const candidate = resolveLocalRefs(node, root);
if (!isPlainObject(candidate) || depth > MAX_NODE_DEPTH) return undefined;
if (candidate[wanted] !== undefined) return candidate;
for (const keyword of ['anyOf', 'oneOf']) {
const branches = candidate[keyword];
if (!Array.isArray(branches)) continue;
for (const branch of branches) {
const found = find(branch, depth + 1);
if (found) return found;
}
}
return undefined;
};
return find(resolved, 0) ?? resolved;
}
function omitNulls(
value: unknown,
schema: unknown,
root: Record<string, unknown>,
depth: number
): unknown {
if (depth > MAX_NODE_DEPTH) {
throw new RangeError(`Tool arguments exceed maximum nesting depth of ${MAX_NODE_DEPTH}`);
}
const node = selectBranchFor(schema, value, root);
if (Array.isArray(value)) {
const items = node && isPlainObject(node.items) ? node.items : undefined;
return value.map(item => omitNulls(item, items, root, depth + 1));
}
if (!isPlainObject(value)) return value;
const properties = node && isPlainObject(node.properties) ? node.properties : {};
const clone: Record<string, unknown> = {};
for (const [key, child] of Object.entries(value)) {
const propertySchema = Object.prototype.hasOwnProperty.call(properties, key)
? properties[key]
: undefined;
if (child === null) {
if (propertySchema === undefined || schemaAcceptsNull(propertySchema, root)) {
setOwn(clone, key, child);
}
continue;
}
setOwn(clone, key, omitNulls(child, propertySchema, root, depth + 1));
}
return clone;
}