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(core): keep optional parameters under strict mode instead of dropping them

jkomyno4f69975475c3
diff --git a/.changeset/strict-schema-normalization.md b/.changeset/strict-schema-normalization.md
index 2443bcda2..ad1cdaee3 100644
--- a/.changeset/strict-schema-normalization.md
+++ b/.changeset/strict-schema-normalization.md
@@ -1,7 +1,7 @@
---
-'@composio/core': patch
+'@composio/core': minor
'@composio/openai': patch
'@composio/vercel': patch
---
-Fix strict-mode tool schemas for OpenAI structured outputs. Strict normalization now recurses into nested objects, nullable types (`type: ['string', 'null']`) and `anyOf`/`allOf`/`oneOf` branches, inlines `$defs`/`$ref`, and marks every object with `additionalProperties: false` plus a complete `required` array — so tools with complex parameters no longer produce schemas the API rejects with a 400. The new `toStrictJsonSchema()` core util returns a change log instead of failing silently; `removeNonRequiredProperties` behavior is unchanged for non-strict callers. The Python `OpenAIResponsesProvider` gains a matching opt-in `strict=True` constructor flag.
+Fix strict-mode tool schemas for OpenAI structured outputs. Strict normalization now applies OpenAI's contract at every depth (nested objects, `anyOf` branches, array items, inlined `$ref`/`$defs`): every object lists all of its properties in `required` and sets `additionalProperties: false`, so tools with nested or optional parameters no longer produce schemas the API rejects with a 400. Optional parameters are no longer dropped: they stay available and are widened to accept `null`, the emulation of optional fields OpenAI documents, and the strict providers drop a `null` argument the tool's own schema does not accept before executing the tool. Tools whose schema strict mode cannot express (objects with arbitrary keys, `allOf`, `prefixItems`, unresolved `$ref`s) are sent without strict mode with a warning naming the tool and path, instead of being narrowed. `@composio/core` exports the new `toStrictJsonSchema()` and `omitNullToolArguments()` utilities; `removeNonRequiredProperties` is unchanged for other callers. The Python `OpenAIResponsesProvider` gains a matching opt-in `strict=True` constructor flag that also emits `strict: true` on the wrapped tool.
diff --git a/ts/packages/core/src/index.ts b/ts/packages/core/src/index.ts
index 49e27e1f5..27ba21561 100644
--- a/ts/packages/core/src/index.ts
+++ b/ts/packages/core/src/index.ts
@@ -9,6 +9,7 @@ export {
deduplicateJsonSchemaRequiredArrays,
ensureObjectTypeOnProperties,
jsonSchemaToZodSchema,
+ omitNullToolArguments,
removeNonRequiredProperties,
toStrictJsonSchema,
} from './utils/jsonSchema';
@@ -18,6 +19,7 @@ export type {
UnresolvedRefStrategy,
StrictSchemaChange,
StrictSchemaChangeReason,
+ StrictSchemaIncompatibility,
StrictJsonSchemaResult,
} from './utils/jsonSchema';
export { getExtensionFromMimeType } from './utils/mime';
diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.ts
index db56ecff1..ff093d080 100644
--- a/ts/packages/core/src/utils/jsonSchema.ts
+++ b/ts/packages/core/src/utils/jsonSchema.ts
@@ -8,6 +8,33 @@ 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
@@ -272,28 +299,6 @@ export function dereferenceJsonSchema<T = unknown>(
export function ensureObjectTypeOnProperties<T = unknown>(schema: T): T {
type WalkMode = 'schema' | 'schema-array' | 'schema-map' | 'dependencies-map' | 'value';
- const schemaKeywords = new Set([
- 'additionalItems',
- 'additionalProperties',
- 'contains',
- 'contentSchema',
- 'else',
- 'if',
- 'not',
- 'propertyNames',
- 'then',
- 'unevaluatedItems',
- 'unevaluatedProperties',
- ]);
- const schemaArrayKeywords = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
- const schemaMapKeywords = new Set([
- '$defs',
- 'definitions',
- 'dependentSchemas',
- 'patternProperties',
- 'properties',
- ]);
-
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}`);
@@ -314,11 +319,11 @@ export function ensureObjectTypeOnProperties<T = unknown>(schema: T): T {
} else if (mode === 'dependencies-map') {
childMode = Array.isArray(child) ? 'value' : 'schema';
} else if (mode === 'schema') {
- if (schemaMapKeywords.has(key)) {
+ if (SCHEMA_MAP_KEYWORDS.has(key)) {
childMode = 'schema-map';
- } else if (schemaArrayKeywords.has(key) || (key === 'items' && Array.isArray(child))) {
+ } else if (SCHEMA_ARRAY_KEYWORDS.has(key) || (key === 'items' && Array.isArray(child))) {
childMode = 'schema-array';
- } else if (schemaKeywords.has(key) || key === 'items') {
+ } else if (SCHEMA_KEYWORDS.has(key) || key === 'items') {
childMode = 'schema';
} else if (key === 'dependencies') {
childMode = 'dependencies-map';
@@ -356,7 +361,6 @@ export function ensureObjectTypeOnProperties<T = unknown>(schema: T): T {
export function deduplicateJsonSchemaRequiredArrays<T = unknown>(schema: T): T {
const seenSchemaValues = new WeakMap<object, unknown>();
const seenInstanceValues = new WeakMap<object, unknown>();
- const instanceValueKeywords = new Set(['const', 'default', 'enum', 'examples']);
function walk(value: unknown, isSchema: boolean, depth = 0): unknown {
if (depth > MAX_NODE_DEPTH) {
@@ -391,7 +395,7 @@ export function deduplicateJsonSchemaRequiredArrays<T = unknown>(schema: T): T {
value:
isSchema && key === 'required' && Array.isArray(child)
? [...new Set(walk(child, false, depth + 1) as unknown[])]
- : walk(child, isSchema && !instanceValueKeywords.has(key), depth + 1),
+ : walk(child, isSchema && !INSTANCE_VALUE_KEYWORDS.has(key), depth + 1),
writable: true,
});
}
@@ -498,24 +502,20 @@ export function jsonSchemaToZodSchema<T extends z.ZodTypeAny>(
}
/**
- * Reason recorded when strict normalization changes a schema node.
+ * Reason recorded when strict normalization rewrites a schema node. Every
+ * rewrite is lossless: the model can still express the same values.
*
- * - `nullable-type-converted` — a `type` array containing `'null'` became an
- * `anyOf` with an explicit `{ type: 'null' }` branch.
- * - `multi-type-converted` — a `type` array without `'null'` (e.g.
- * `['string', 'number']`) became equivalent `anyOf` branches.
- * - `annotation-keyword-stripped` — an annotation-only keyword (`examples`,
- * `default`) that strict mode rejects was removed.
- * - `non-required-property-dropped` — a property not listed in `required`
- * was removed from its parent object.
+ * - `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 =
- | 'nullable-type-converted'
- | 'multi-type-converted'
- | 'annotation-keyword-stripped'
- | 'non-required-property-dropped';
+ 'optional-property-nullable' | 'unsupported-keyword-stripped' | 'one-of-converted';
-/** A single structural change applied by {@link toStrictJsonSchema}. */
+/** 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;
@@ -524,10 +524,36 @@ export interface StrictSchemaChange {
detail?: string;
}
-/** Result of {@link toStrictJsonSchema}: the normalized schema plus a change log. */
-export interface StrictJsonSchemaResult<T = unknown> {
- schema: T;
+/**
+ * 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 dereferenced input 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;
@@ -535,84 +561,99 @@ const MAX_STRICT_CHANGES = 50;
/** Annotation-only keywords OpenAI structured outputs rejects; safe to strip. */
const STRICT_STRIP_KEYWORDS = new Set(['examples', 'default']);
-/** Keywords whose values are literal data, not schemas — never recursed as schemas. */
-const STRICT_INSTANCE_VALUE_KEYWORDS = new Set(['const', 'enum']);
-
-const STRICT_SCHEMA_SINGLE_KEYS = new Set([
- 'additionalItems',
- 'additionalProperties',
- 'contains',
- 'contentSchema',
- 'else',
- 'if',
- 'not',
- 'propertyNames',
- 'then',
- 'unevaluatedItems',
- 'unevaluatedProperties',
-]);
-const STRICT_SCHEMA_ARRAY_KEYS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
-const STRICT_SCHEMA_MAP_KEYS = new Set([
- '$defs',
- 'definitions',
- 'dependentSchemas',
- 'patternProperties',
- 'properties',
-]);
+/** Keywords OpenAI structured outputs reject and that have no lossless rewrite. */
+const STRICT_UNSUPPORTED_KEYWORDS = ['allOf', 'prefixItems'];
type StrictWalkMode = 'schema' | 'schema-array' | 'schema-map' | 'value';
+const joinPath = (parent: string, key: string): string => (parent ? `${parent}.${key}` : key);
+
/**
- * Normalizes a JSON Schema for OpenAI structured outputs (`strict: true`),
- * which requires every object node to declare all of its properties in
- * `required`, set `additionalProperties: false`, use only supported keywords,
- * and express nullable / multi-typed fields via `anyOf`.
- *
- * The top-level `removeNonRequiredProperties` only handled the root object,
- * so nested objects, composition branches and array items passed through
- * untouched and the API rejected the whole request. This function applies the
- * same contract at every depth:
+ * 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'] };
+ }
+ // 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' }],
+ };
+}
+
+/** Whether a (dereferenced) schema node accepts `null` as an instance. */
+function schemaAcceptsNull(node: unknown): boolean {
+ 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(schemaAcceptsNull);
+ }
+ return true;
+}
+
+/**
+ * Normalizes a tool parameter schema for OpenAI structured outputs
+ * (`strict: true`) at every depth, following the contract OpenAI documents:
*
- * - Objects with a non-empty `required` keep only those properties
- * (matching the established top-level behavior); objects without one keep
- * every property but are forced to require them all — dropping everything
- * would gut the tool, and leaving optional properties would be rejected.
- * - `type` arrays become `anyOf` branches with an explicit `{type:'null'}`
- * variant where applicable.
- * - Annotation keywords (`examples`, `default`) are stripped.
- * - Composition keywords (`anyOf`/`oneOf`/`allOf`), array `items`/
- * `prefixItems` and property maps are normalized recursively.
+ * - 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;
+ * - constructs strict mode cannot express — objects that accept arbitrary
+ * keys (schema-valued or `true` `additionalProperties`, `patternProperties`,
+ * property-less free-form objects), `allOf`, `prefixItems`, dangling or
+ * cyclic `$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.
*
- * Every structural change is recorded so callers can surface diagnostics
- * instead of failing silently. The input is never mutated. Dereference
- * `$ref`s first (see {@link dereferenceJsonSchema}) so definitions referenced
- * under `$defs` are normalized too, then run
- * {@link deduplicateJsonSchemaRequiredArrays} on the result before emitting.
+ * The pipeline is `dereferenceJsonSchema` (lenient) → strict rewrite →
+ * `deduplicateJsonSchemaRequiredArrays`, the same shape the Anthropic
+ * provider uses. The input is never mutated. Every rewrite is recorded in
+ * `changes` (capped at 50 entries; `totalChanges` carries the real count).
*/
-export function toStrictJsonSchema<T = unknown>(schema: T): StrictJsonSchemaResult<T> {
+export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
const changes: StrictSchemaChange[] = [];
+ const unsupported: StrictSchemaIncompatibility[] = [];
+ let totalChanges = 0;
const recordChange = (change: StrictSchemaChange): void => {
- if (changes.length < MAX_STRICT_CHANGES) {
- changes.push(change);
- }
+ totalChanges += 1;
+ if (changes.length < MAX_STRICT_CHANGES) changes.push(change);
};
- const joinPath = (parent: string, key: string): string =>
- parent ? `${parent}.${key}` : key;
-
- const splitTypeArray = (node: Record<string, unknown>, path: string): Record<string, unknown> => {
- const typeValues = node.type as unknown[];
- const branches = typeValues.map(typeValue =>
- typeValue === 'null' ? { type: 'null' } : { ...node, type: typeValue }
- );
- const { type: _droppedType, ...rest } = node;
- recordChange({
- path,
- reason: typeValues.includes('null') ? 'nullable-type-converted' : 'multi-type-converted',
- detail: `type [${typeValues.map(String).join(', ')}] converted to anyOf`,
- });
- return { ...rest, anyOf: branches };
- };
+ const dereferenced = dereferenceJsonSchema(schema, {
+ onUnresolved: 'sentinel',
+ onReplace: ref =>
+ unsupported.push({
+ path: '',
+ keyword: '$ref',
+ detail: `unresolved $ref "${ref}"`,
+ }),
+ });
function walkChildren(
node: Record<string, unknown>,
@@ -625,22 +666,25 @@ export function toStrictJsonSchema<T = unknown>(schema: T): StrictJsonSchemaResu
let childMode: StrictWalkMode = 'value';
if (mode === 'schema-map') {
childMode = 'schema';
- } else if (mode === 'schema') {
- if (!STRICT_INSTANCE_VALUE_KEYWORDS.has(key)) {
- if (STRICT_SCHEMA_MAP_KEYS.has(key)) {
- childMode = 'schema-map';
- } else if (STRICT_SCHEMA_ARRAY_KEYS.has(key) || (key === 'items' && Array.isArray(child))) {
- childMode = 'schema-array';
- } else if (STRICT_SCHEMA_SINGLE_KEYS.has(key) || key === 'items') {
- 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)) {
- mapClone[name] = walk(subSchema, 'schema', depth + 1, joinPath(joinPath(path, key), name));
+ mapClone[name] = walk(
+ subSchema,
+ 'schema',
+ depth + 1,
+ joinPath(joinPath(path, key), name)
+ );
}
clone[key] = mapClone;
continue;
@@ -658,84 +702,146 @@ export function toStrictJsonSchema<T = unknown>(schema: T): StrictJsonSchemaResu
const itemMode = mode === 'schema-array' ? 'schema' : 'value';
return value.map((item, index) => walk(item, itemMode, depth + 1, `${path}[${index}]`));
}
- if (!isPlainObject(value)) return value;
- if (mode === 'value') return value;
-
- let node: Record<string, unknown> = value;
+ if (!isPlainObject(value) || mode === 'value') return value;
- // Nullable / multi-type arrays must become anyOf before anything else so
- // the generated branches flow through the normal recursion below.
- if (Array.isArray(node.type)) {
- node = splitTypeArray(node, path);
- }
-
- const strippedNode: Record<string, unknown> = {};
- for (const [key, child] of Object.entries(node)) {
+ const node: Record<string, unknown> = {};
+ for (const [key, child] of Object.entries(value)) {
if (STRICT_STRIP_KEYWORDS.has(key)) {
recordChange({
path,
- reason: 'annotation-keyword-stripped',
+ reason: 'unsupported-keyword-stripped',
detail: `keyword "${key}" removed`,
});
continue;
}
- strippedNode[key] = child;
+ node[key] = child;
}
- node = strippedNode;
-
- // Object strictening: complete required, closed additionalProperties.
- const hasPropertiesKeyword = isPlainObject(node.properties);
- const isObjectNode = hasPropertiesKeyword || node.type === 'object';
- if (isObjectNode) {
- const properties = hasPropertiesKeyword
- ? (node.properties as Record<string, unknown>)
- : {};
- const declaredRequired = Array.isArray(node.required)
- ? node.required.filter((entry): entry is string => typeof entry === 'string')
- : [];
- const keepOnlyRequired = declaredRequired.length > 0;
- const keptKeys = new Set(
- keepOnlyRequired ? declaredRequired.filter(key => key in properties) : Object.keys(properties)
- );
-
- const nextProperties: Record<string, unknown> = {};
- for (const [name, propertySchema] of Object.entries(properties)) {
- if (keptKeys.has(name)) {
- nextProperties[name] = walk(
- propertySchema,
- 'schema',
- depth + 1,
- joinPath(path, `properties.${name}`)
- );
- } else {
- recordChange({
- path: joinPath(path, `properties.${name}`),
- reason: 'non-required-property-dropped',
- detail: `property "${name}" is not listed in "required"`,
- });
- }
+ 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`,
+ });
}
+ }
- // Recurse into any remaining schema-bearing siblings (e.g. `allOf`,
- // `description`) while keeping the four managed keywords authoritative.
- const managedKeys = new Set(['type', 'properties', 'required', 'additionalProperties']);
- const restNode: Record<string, unknown> = {};
- for (const [key, child] of Object.entries(node)) {
- if (!managedKeys.has(key)) restNode[key] = child;
- }
+ const out = walkChildren(node, mode, depth, path);
+
+ const declaresObjectType =
+ out.type === 'object' || (Array.isArray(out.type) && out.type.includes('object'));
+ if (!declaresObjectType && !isPlainObject(out.properties)) return out;
+
+ const properties: Record<string, unknown> = isPlainObject(out.properties)
+ ? { ...out.properties }
+ : {};
+ const declaredRequired = new Set(
+ Array.isArray(out.required) ? out.required.filter(entry => typeof entry === 'string') : []
+ );
+ for (const [name, propertySchema] of Object.entries(properties)) {
+ if (declaredRequired.has(name) || !isPlainObject(propertySchema)) continue;
+ properties[name] = widenToNullable(propertySchema);
+ recordChange({
+ path: joinPath(path, `properties.${name}`),
+ reason: 'optional-property-nullable',
+ detail: `property "${name}" is now required and accepts null`,
+ });
+ }
- return {
- ...walkChildren(restNode, 'schema', depth, path),
- type: 'object',
- properties: nextProperties,
- required: Object.keys(nextProperties),
- additionalProperties: false,
- };
+ 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 walkChildren(node, mode, depth, path);
+ return {
+ ...out,
+ ...(out.type === undefined ? { type: 'object' } : {}),
+ properties,
+ required: Object.keys(properties),
+ ...(acceptsDynamicKeys ? {} : { additionalProperties: false }),
+ };
+ }
+
+ const normalized = walk(dereferenced, 'schema', 0, '');
+ if (!isPlainObject(normalized) || normalized.type !== 'object') {
+ unsupported.push({
+ path: '',
+ keyword: 'type',
+ detail: 'root must be a non-nullable object',
+ });
}
- const normalized = walk(schema, 'schema', 0, '');
- return { schema: normalized as T, changes };
+ return {
+ schema: deduplicateJsonSchemaRequiredArrays(normalized) as Record<string, unknown>,
+ source: dereferenced as Record<string, unknown>,
+ 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> {
+ return omitNulls(args, schema) as Record<string, unknown>;
+}
+
+function omitNulls(value: unknown, schema: unknown): unknown {
+ const node = isPlainObject(schema) ? schema : undefined;
+ if (Array.isArray(value)) {
+ const items = node && isPlainObject(node.items) ? node.items : undefined;
+ return value.map(item => omitNulls(item, items));
+ }
+ 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 = properties[key];
+ if (child === null) {
+ if (propertySchema === undefined || schemaAcceptsNull(propertySchema)) clone[key] = child;
+ continue;
+ }
+ clone[key] = omitNulls(child, propertySchema);
+ }
+ return clone;
}
diff --git a/ts/packages/core/test/utils/jsonSchema.strict.test.ts b/ts/packages/core/test/utils/jsonSchema.strict.test.ts
index 122220cdd..1b6732160 100644
--- a/ts/packages/core/test/utils/jsonSchema.strict.test.ts
+++ b/ts/packages/core/test/utils/jsonSchema.strict.test.ts
@@ -1,14 +1,39 @@
import { describe, it, expect } from 'vitest';
-import {
- deduplicateJsonSchemaRequiredArrays,
- dereferenceJsonSchema,
- toStrictJsonSchema,
-} from '../../src/utils/jsonSchema';
+import { omitNullToolArguments, toStrictJsonSchema } from '../../src/utils/jsonSchema';
+import type { StrictSchemaChange } from '../../src/utils/jsonSchema';
-const propertyOf = (schema: unknown, name: string): Record<string, unknown> =>
- ((schema as Record<string, unknown>).properties as Record<string, string>)[
- name
- ] as unknown as Record<string, unknown>;
+const propertyOf = (schema: Record<string, unknown>, name: string): Record<string, unknown> =>
+ (schema.properties as Record<string, Record<string, unknown>>)[name];
+
+const reasons = (changes: StrictSchemaChange[]): string[] => changes.map(change => change.reason);
+
+/** Structural invariants OpenAI enforces on every node of a strict schema. */
+function assertStrictShape(node: unknown, path = ''): void {
+ if (Array.isArray(node)) {
+ node.forEach((item, index) => assertStrictShape(item, `${path}[${index}]`));
+ return;
+ }
+ if (!node || typeof node !== 'object') return;
+ const record = node as Record<string, unknown>;
+ if (record.anyOf !== undefined) {
+ expect(record.type, `${path}: type beside anyOf`).toBeUndefined();
+ }
+ expect(record.default, `${path}: default`).toBeUndefined();
+ expect(record.examples, `${path}: examples`).toBeUndefined();
+ expect(record.oneOf, `${path}: oneOf`).toBeUndefined();
+ expect(record.patternProperties, `${path}: patternProperties`).toBeUndefined();
+ const isObject =
+ record.type === 'object' || (Array.isArray(record.type) && record.type.includes('object'));
+ if (isObject || record.properties !== undefined) {
+ const properties = (record.properties ?? {}) as Record<string, unknown>;
+ expect(record.required, `${path}: required`).toEqual(Object.keys(properties));
+ expect(record.additionalProperties, `${path}: additionalProperties`).toBe(false);
+ }
+ for (const [key, child] of Object.entries(record)) {
+ if (key === 'enum' || key === 'const') continue;
+ assertStrictShape(child, path ? `${path}.${key}` : key);
+ }
+}
describe('toStrictJsonSchema', () => {
it('keeps an already-flat all-required object valid', () => {
@@ -25,15 +50,15 @@ describe('toStrictJsonSchema', () => {
expect(changes).toEqual([]);
});
- it('drops nested non-required properties and closes every object', () => {
- const { schema } = toStrictJsonSchema({
+ it('keeps optional properties, requires them and widens them to accept null', () => {
+ const { schema, changes } = toStrictJsonSchema({
type: 'object',
properties: {
cfg: {
type: 'object',
properties: {
url: { type: 'string' },
- note: { type: 'string' },
+ note: { type: 'string', description: 'optional note' },
},
required: ['url'],
},
@@ -48,17 +73,25 @@ describe('toStrictJsonSchema', () => {
type: 'object',
properties: {
url: { type: 'string' },
+ note: { type: ['string', 'null'], description: 'optional note' },
},
- required: ['url'],
+ required: ['url', 'note'],
additionalProperties: false,
},
},
required: ['cfg'],
additionalProperties: false,
});
+ expect(changes).toEqual([
+ {
+ path: 'properties.cfg.properties.note',
+ reason: 'optional-property-nullable',
+ detail: 'property "note" is now required and accepts null',
+ },
+ ]);
});
- it('requires every property when the object has no required array', () => {
+ it('requires and widens every property when the object has no required array', () => {
const { schema } = toStrictJsonSchema({
type: 'object',
properties: {
@@ -70,51 +103,75 @@ describe('toStrictJsonSchema', () => {
expect(schema).toEqual({
type: 'object',
properties: {
- a: { type: 'string' },
- b: { type: 'number' },
+ a: { type: ['string', 'null'] },
+ b: { type: ['number', 'null'] },
},
required: ['a', 'b'],
additionalProperties: false,
});
});
- it('converts nullable type arrays into anyOf with an explicit null branch', () => {
- const { schema } = toStrictJsonSchema({
+ it('keeps nullable type arrays as-is and closes nullable objects', () => {
+ const { schema, changes } = toStrictJsonSchema({
type: 'object',
properties: {
id: { type: ['string', 'null'], description: 'identifier' },
+ cfg: {
+ type: ['object', 'null'],
+ properties: { a: { type: 'string' } },
+ required: ['a'],
+ },
+ xs: { type: ['array', 'null'], items: { type: 'string' } },
},
- required: ['id'],
+ required: ['id', 'cfg', 'xs'],
});
expect(schema).toEqual({
type: 'object',
properties: {
- id: {
- anyOf: [{ type: 'string', description: 'identifier' }, { type: 'null' }],
- description: 'identifier',
+ id: { type: ['string', 'null'], description: 'identifier' },
+ cfg: {
+ type: ['object', 'null'],
+ properties: { a: { type: 'string' } },
+ required: ['a'],
+ additionalProperties: false,
},
+ xs: { type: ['array', 'null'], items: { type: 'string' } },
},
- required: ['id'],
+ required: ['id', 'cfg', 'xs'],
additionalProperties: false,
});
+ expect(changes).toEqual([]);
+ assertStrictShape(schema);
});
- it('converts multi-type arrays into anyOf branches', () => {
+ it('widens optional composition and enum-only properties without placing type beside anyOf', () => {
const { schema } = toStrictJsonSchema({
type: 'object',
properties: {
- value: { type: ['string', 'number'] },
+ value: { anyOf: [{ type: 'string' }, { type: 'number' }] },
+ already: { anyOf: [{ type: 'string' }, { type: 'null' }] },
+ choice: { enum: ['a', 'b'], description: 'pick one' },
+ multi: { type: ['string', 'number'] },
},
- required: ['value'],
});
- const property = propertyOf(schema, 'value');
- expect(property.anyOf).toEqual([{ type: 'string' }, { type: 'number' }]);
+ expect(propertyOf(schema, 'value')).toEqual({
+ anyOf: [{ type: 'string' }, { type: 'number' }, { type: 'null' }],
+ });
+ expect(propertyOf(schema, 'already')).toEqual({
+ anyOf: [{ type: 'string' }, { type: 'null' }],
+ });
+ expect(propertyOf(schema, 'choice')).toEqual({
+ description: 'pick one',
+ anyOf: [{ enum: ['a', 'b'] }, { type: 'null' }],
+ });
+ expect(propertyOf(schema, 'multi')).toEqual({ type: ['string', 'number', 'null'] });
+ assertStrictShape(schema);
});
- it('normalizes composition branches recursively', () => {
- const { schema } = toStrictJsonSchema({
+ it('normalizes composition branches and array items recursively', () => {
+ const { schema, changes } = toStrictJsonSchema({
type: 'object',
properties: {
payload: {
@@ -127,23 +184,6 @@ describe('toStrictJsonSchema', () => {
{ type: 'null' },
],
},
- },
- required: ['payload'],
- });
-
- const payload = propertyOf(schema, 'payload');
- expect(payload.anyOf[0]).toEqual({
- type: 'object',
- properties: { inner: { type: 'string' } },
- required: ['inner'],
- additionalProperties: false,
- });
- });
-
- it('normalizes array item schemas including tuples', () => {
- const { schema } = toStrictJsonSchema({
- type: 'object',
- properties: {
rows: {
type: 'array',
items: {
@@ -152,59 +192,145 @@ describe('toStrictJsonSchema', () => {
required: ['id'],
},
},
- pair: {
- type: 'array',
- prefixItems: [
- { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } } },
- ],
- },
+ either: { oneOf: [{ type: 'string' }, { type: 'number' }] },
},
- required: ['rows', 'pair'],
+ required: ['payload', 'rows', 'either'],
});
- const props = (schema as Record<string, unknown>).properties as Record<
- string,
- Record<string, unknown>
- >;
- expect(props.rows.items).toEqual({
+ expect((propertyOf(schema, 'payload').anyOf as unknown[])[0]).toEqual({
type: 'object',
- properties: { id: { type: 'string' } },
- required: ['id'],
+ properties: { inner: { type: 'string' }, extra: { type: ['string', 'null'] } },
+ required: ['inner', 'extra'],
additionalProperties: false,
});
- expect(props.pair.prefixItems[0]).toEqual({
+ expect(propertyOf(schema, 'rows').items).toEqual({
type: 'object',
- properties: { x: { type: 'number' }, y: { type: 'number' } },
- required: ['x', 'y'],
+ properties: { id: { type: 'string' }, tag: { type: ['string', 'null'] } },
+ required: ['id', 'tag'],
additionalProperties: false,
});
+ expect(propertyOf(schema, 'either')).toEqual({
+ anyOf: [{ type: 'string' }, { type: 'number' }],
+ });
+ expect(reasons(changes)).toContain('one-of-converted');
+ assertStrictShape(schema);
});
- it('strips annotation keywords and reports them', () => {
- const { schema, changes } = toStrictJsonSchema({
+ it('reports dynamic-key and free-form objects as unsupported instead of closing them', () => {
+ const { schema, unsupported } = toStrictJsonSchema({
type: 'object',
- properties: { name: { type: 'string', examples: ['a'], default: 'x' } },
- required: ['name'],
+ properties: {
+ headers: { type: 'object', additionalProperties: { type: 'string' } },
+ meta: { type: 'object', description: 'any json' },
+ tagged: { type: 'object', patternProperties: { '^x-': { type: 'string' } } },
+ open: { type: 'object', additionalProperties: true },
+ },
+ required: ['headers', 'meta', 'tagged', 'open'],
+ });
+
+ expect(unsupported).toEqual([
+ {
+ path: 'properties.headers',
+ keyword: 'additionalProperties',
+ detail: 'object accepts arbitrary keys',
+ },
+ {
+ path: 'properties.meta',
+ keyword: 'properties',
+ detail: 'free-form object accepts arbitrary keys',
+ },
+ {
+ path: 'properties.tagged',
+ keyword: 'patternProperties',
+ detail: 'object accepts pattern-matched keys',
+ },
+ {
+ path: 'properties.open',
+ keyword: 'additionalProperties',
+ detail: 'object accepts arbitrary keys',
+ },
+ ]);
+ // The schema-valued additionalProperties is preserved, not overwritten.
+ expect(propertyOf(schema, 'headers').additionalProperties).toEqual({ type: 'string' });
+ expect(propertyOf(schema, 'tagged').patternProperties).toBeDefined();
+ });
+
+ it('strips annotation keywords and reports keywords it cannot rewrite', () => {
+ const { schema, changes, unsupported } = toStrictJsonSchema({
+ type: 'object',
+ properties: {
+ name: { type: 'string', examples: ['a'], default: 'x' },
+ pair: { type: 'array', prefixItems: [{ type: 'number' }] },
+ all: { allOf: [{ type: 'string' }] },
+ },
+ required: ['name', 'pair', 'all'],
});
expect(propertyOf(schema, 'name')).toEqual({ type: 'string' });
- expect(changes.filter(change => change.reason === 'annotation-keyword-stripped')).toHaveLength(
+ expect(changes.filter(change => change.reason === 'unsupported-keyword-stripped')).toHaveLength(
2
);
+ expect(unsupported.map(entry => [entry.path, entry.keyword])).toEqual([
+ ['properties.pair', 'prefixItems'],
+ ['properties.all', 'allOf'],
+ ]);
+ });
+
+ it('inlines $ref/$defs, dedupes required and reports dangling refs', () => {
+ const { schema, changes, unsupported } = toStrictJsonSchema({
+ type: 'object',
+ properties: {
+ cfg: { $ref: '#/$defs/Config' },
+ missing: { $ref: '#/$defs/Nope' },
+ },
+ required: ['cfg', 'cfg', 'missing'],
+ $defs: {
+ Config: {
+ type: 'object',
+ properties: { url: { type: 'string' }, note: { type: 'string' } },
+ required: ['url'],
+ },
+ },
+ });
+
+ expect(JSON.stringify(schema)).not.toContain('$ref');
+ expect(schema.$defs).toBeUndefined();
+ expect(propertyOf(schema, 'cfg')).toEqual({
+ type: 'object',
+ properties: { url: { type: 'string' }, note: { type: ['string', 'null'] } },
+ required: ['url', 'note'],
+ additionalProperties: false,
+ });
+ expect(schema.required).toEqual(['cfg', 'missing']);
+ expect(unsupported).toEqual([
+ { path: '', keyword: '$ref', detail: 'unresolved $ref "#/$defs/Nope"' },
+ {
+ path: 'properties.missing',
+ keyword: 'additionalProperties',
+ detail: 'object accepts arbitrary keys',
+ },
+ ]);
+ expect(changes).toContainEqual(
+ expect.objectContaining({
+ path: 'properties.cfg.properties.note',
+ reason: 'optional-property-nullable',
+ })
+ );
});
- it('reports dropped properties as changes without exceeding the cap', () => {
+ it('caps the change log at 50 entries without losing properties', () => {
const properties: Record<string, unknown> = {};
for (let i = 0; i < 60; i++) properties[`p${i}`] = { type: 'string' };
- const { schema, changes } = toStrictJsonSchema({
+ const { schema, changes, totalChanges } = toStrictJsonSchema({
type: 'object',
properties,
required: ['p0'],
});
- expect(Object.keys((schema as Record<string, unknown>).properties as object)).toEqual(['p0']);
- expect(changes.length).toBeLessThanOrEqual(50);
+ expect(Object.keys(schema.properties as object)).toHaveLength(60);
+ expect(changes).toHaveLength(50);
+ expect(totalChanges).toBe(59);
});
it('does not mutate the input schema', () => {
@@ -213,7 +339,7 @@ describe('toStrictJsonSchema', () => {
properties: {
cfg: {
type: 'object',
- properties: { opt: { type: 'string' } },
+ properties: { opt: { type: 'string', default: 1 } },
},
},
required: ['cfg'],
@@ -225,20 +351,13 @@ describe('toStrictJsonSchema', () => {
expect(input).toEqual(snapshot);
});
- it('is idempotent for composed pipelines', () => {
- const pipeline = (input: unknown): unknown =>
- deduplicateJsonSchemaRequiredArrays(
- toStrictJsonSchema(dereferenceJsonSchema(input, { onUnresolved: 'sentinel' })).schema
- );
-
- const once = pipeline({
+ it('is idempotent', () => {
+ const once = toStrictJsonSchema({
type: 'object',
properties: {
- cfg: {
- $ref: '#/$defs/Config',
- },
+ cfg: { $ref: '#/$defs/Config' },
+ id: { type: ['string', 'null'] },
},
- required: ['cfg'],
$defs: {
Config: {
type: 'object',
@@ -246,9 +365,39 @@ describe('toStrictJsonSchema', () => {
required: ['url'],
},
},
- });
+ }).schema;
+
+ const twice = toStrictJsonSchema(once);
+ expect(twice.schema).toEqual(once);
+ expect(twice.changes).toEqual([]);
+ expect(twice.unsupported).toEqual([]);
+ });
+
+ it('reports non-object and cyclic roots as unsupported', () => {
+ expect(toStrictJsonSchema({ type: 'string' }).unsupported).toEqual([
+ { path: '', keyword: 'type', detail: 'root must be a non-nullable object' },
+ ]);
+ expect(
+ toStrictJsonSchema({ type: ['object', 'null'], properties: { a: { type: 'string' } } })
+ .unsupported
+ ).toContainEqual(expect.objectContaining({ path: '', keyword: 'type' }));
- expect(pipeline(once)).toEqual(once);
+ const cyclic = toStrictJsonSchema({
+ type: 'object',
+ properties: { node: { $ref: '#/$defs/Node' } },
+ required: ['node'],
+ $defs: {
+ Node: {
+ type: 'object',
+ properties: { child: { $ref: '#/$defs/Node' } },
+ required: ['child'],
+ },
+ },
+ });
+ // The cycle-break sentinel is a free-form object, which strict mode cannot express.
+ expect(cyclic.unsupported).toContainEqual(
+ expect.objectContaining({ keyword: 'additionalProperties' })
+ );
});
it('throws past the maximum nesting depth', () => {
@@ -257,6 +406,47 @@ describe('toStrictJsonSchema', () => {
deep = { type: 'object', properties: { nest: deep }, required: ['nest'] };
}
- expect(() => toStrictJsonSchema(deep)).toThrow(RangeError);
+ expect(() => toStrictJsonSchema(deep)).toThrow(/depth/);
+ });
+});
+
+describe('omitNullToolArguments', () => {
+ const schema = {
+ type: 'object',
+ properties: {
+ cfg: {
+ type: 'object',
+ properties: { url: { type: 'string' }, note: { type: 'string' } },
+ required: ['url'],
+ },
+ label: { type: 'string' },
+ clearable: { type: ['string', 'null'] },
+ choice: { anyOf: [{ enum: ['a'] }, { type: 'null' }] },
+ rows: {
+ type: 'array',
+ items: { type: 'object', properties: { id: { type: 'string' }, tag: { type: 'string' } } },
+ },
+ },
+ };
+
+ it('drops nulls the schema does not accept and keeps the ones it does', () => {
+ const input = {
+ cfg: { url: 'https://example.com', note: null },
+ label: null,
+ clearable: null,
+ choice: null,
+ unknown: null,
+ rows: [{ id: '1', tag: null }, null],
+ };
+ const snapshot = JSON.parse(JSON.stringify(input));
+
+ expect(omitNullToolArguments(input, schema)).toEqual({
+ cfg: { url: 'https://example.com' },
+ clearable: null,
+ choice: null,
+ unknown: null,
+ rows: [{ id: '1' }, null],
+ });
+ expect(input).toEqual(snapshot);
});
});