@devries-cameron20 / composio Mirror · read-only / commits / 48d3559e5
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 09:45 UTC

fix(core): keep every constraint when widening strict parameters to null (#4773)

Optional typed enum and const parameters were widened by adding null to their type only, so the strict schema still rejected the null that stands for omission. Null acceptance is now decided in one place with every keyword, a property is wrapped whole unless type or anyOf is its only obstacle, and a null argument is dropped unless the tool's schema accepts it. Null checks are remembered per schema node and bounded in depth and work. A $ref whose target the rewrite moved is reported as unsupported. Fixes #4755

Alberto Schiabel committed Oct 8, 2026 at 16:16 UTC 48d3559e5fd6ce296614f75617aeb54e77a8ee60
12 files changed +2508 -77
.changeset/strict-null-widening.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/core': patch
3 +---
4 +
5 +Fix optional enum and const parameters under strict mode. A typed enum such as `{ "type": "string", "enum": ["asc", "desc"] }` was widened by adding `null` to its `type` only, so the enum still rejected `null` and the model could not omit the parameter. Such schemas are now wrapped whole in `anyOf` with a `null` branch, as are `type` beside `anyOf` and `$ref` with sibling keywords. `omitNullToolArguments` now keeps a `null` only when every keyword of the tool's schema accepts it, so a `null` that an `enum`, `const`, `$ref` sibling or `allOf` rejects is treated as an omitted argument. Schemas whose only obstacle to `null` is `type` or `anyOf` are emitted exactly as before. A tool whose schema holds a `$ref` into a property that wrapping moves is reported in `unsupported` and sent without strict mode. Null checks remember their answer per schema node and are bounded in depth and work, so a schema whose definitions fan out through shared references stays cheap.
pnpm-lock.yaml
+6
@@ -1388,6 +1388,12 @@ importers:
1388 '@types/semver':
1389 specifier: ^7.8.0
1390 version: 7.8.0
1391 + ajv:
1392 + specifier: ^8.20.0
1393 + version: 8.20.0
1394 + fast-check:
1395 + specifier: ^4.10.2
1396 + version: 4.10.2
1397 hono:
1398 specifier: 'catalog:'
1399 version: 4.13.9
python/composio/utils/strict_schema.py
+208 -41
@@ -34,6 +34,9 @@ from composio.utils.json_schema import MAX_REF_CHAIN_DEPTH, _try_resolve_pointer
34
35 MAX_NODE_DEPTH = 512
36 MAX_CHANGES = 50
37 +# Bounds on one null-acceptance check; past either, null is not proven accepted.
38 +MAX_NULL_CHECK_DEPTH = 64
39 +MAX_NULL_CHECK_NODES = 2_000
40
41 # Annotation-only keywords OpenAI structured outputs rejects; safe to strip.
42 STRICT_STRIP_KEYWORDS = frozenset({"examples", "default"})
@@ -125,28 +128,46 @@ def _join_path(parent: str, key: str) -> str:
128 return f"{parent}.{key}" if parent else key
129
130
128 -def _widen_to_nullable(node: dict[str, t.Any]) -> dict[str, t.Any]:
129 - """Accept ``null`` without placing ``type`` beside ``anyOf``."""
130 - any_of = node.get("anyOf")
131 - if isinstance(any_of, list):
132 - if any(isinstance(b, dict) and b.get("type") == "null" for b in any_of):
133 - return node
134 - return {**node, "anyOf": [*any_of, {"type": "null"}]}
135 - node_type = node.get("type")
136 - if isinstance(node_type, str):
137 - return node if node_type == "null" else {**node, "type": [node_type, "null"]}
138 - if isinstance(node_type, list):
139 - return node if "null" in node_type else {**node, "type": [*node_type, "null"]}
140 - if (isinstance(node.get("enum"), list) and None in node["enum"]) or (
141 - "const" in node and node["const"] is None
142 - ):
131 +# The only keywords that can reject a ``null`` instance; every other keyword
132 +# constrains strings, numbers, arrays or objects and ignores ``null``.
133 +NULL_CONSTRAINT_KEYWORDS = (
134 + "type",
135 + "enum",
136 + "const",
137 + "$ref",
138 + "anyOf",
139 + "oneOf",
140 + "allOf",
141 + "not",
142 + "if",
143 + "then",
144 + "else",
145 +)
146 +
147 +
148 +def _widen_to_nullable(
149 + node: dict[str, t.Any], null_check: _NullCheck
150 +) -> dict[str, t.Any]:
151 + """Accept ``null`` while keeping every other constraint the node declares.
152 +
153 + A node whose only obstacle is ``type`` or ``anyOf`` is widened in place.
154 + Anything else is wrapped whole, because JSON Schema keywords apply
155 + together: adding ``null`` to ``type`` does not lift a sibling ``enum``.
156 + ``null_check`` must answer for the strict output.
157 + """
158 + if null_check.accepts(node):
159 return node
160 + constraints = [key for key in NULL_CONSTRAINT_KEYWORDS if key in node]
161 + if constraints == ["type"]:
162 + node_type = node["type"]
163 + members = node_type if isinstance(node_type, list) else [node_type]
164 + return {**node, "type": [*members, "null"]}
165 + if constraints == ["anyOf"]:
166 + return {**node, "anyOf": [*node["anyOf"], {"type": "null"}]}
167 annotations: dict[str, t.Any] = {
168 k: node[k] for k in ("description", "title") if k in node
169 }
170 rest = {k: v for k, v in node.items() if k not in annotations}
148 - if not rest:
149 - return node
171 return {**annotations, "anyOf": [rest, {"type": "null"}]}
172
173
@@ -163,25 +184,155 @@ def _resolve_local_refs(node: t.Any, root: dict[str, t.Any]) -> t.Any:
184 return current
185
186
166 -def _schema_accepts_null(schema: t.Any, root: dict[str, t.Any]) -> bool:
167 - """Whether a schema node accepts ``null`` as an instance."""
168 - node = _resolve_local_refs(schema, root)
169 - if not isinstance(node, dict):
187 +# Markers for what an answer leans on, besides the depth of a node on the path.
188 +_NOTHING = MAX_NULL_CHECK_DEPTH + 1
189 +_A_BOUND = -1
190 +
191 +
192 +class _NullCheck:
193 + """Decides whether schemas of one document accept ``null`` as an instance.
194 +
195 + Every keyword in :data:`NULL_CONSTRAINT_KEYWORDS` that is present must
196 + accept it. This is the single definition of null acceptance: the strict
197 + rewrite and :func:`omit_null_tool_arguments` both decide with it.
198 +
199 + ``strict_output`` answers for the schema :func:`to_strict_json_schema`
200 + emits instead of the one it was given: the rewrite types every node that
201 + declares ``properties`` as an object, so such a node stops accepting null.
202 +
203 + One instance serves every check against a document, and an answer is
204 + computed once per node. A reference cycle never yields a null by itself,
205 + so a node met again while it is being evaluated counts as rejecting. An
206 + answer that leans on that is provisional until the node it leans on is
207 + done: it is kept if that node does reject null and discarded otherwise.
208 +
209 + Each check is bounded in depth and in nodes visited. A check that meets a
210 + bound proves nothing, so it rejects null whatever its other branches say,
211 + which costs at most a redundant null branch or a dropped null. The nodes
212 + it went through stay marked as unproven, so a later check that reaches
213 + one of them neither repeats the work nor trusts the answer.
214 + """
215 +
216 + def __init__(self, root: dict[str, t.Any], strict_output: bool = False) -> None:
217 + self.root = root
218 + self.strict_output = strict_output
219 + # id(node) -> (node, answer, what it leans on). Holding the node keeps
220 + # its id from being reused while the answer is remembered.
221 + self.answers: dict[int, tuple[dict[str, t.Any], bool, int]] = {}
222 + # Nodes whose answer is provisional, oldest first.
223 + self.provisional: list[int] = []
224 + # Nodes being evaluated, mapped to their depth on the current path.
225 + self.path: dict[int, int] = {}
226 + # Depths of the path nodes that were met again below themselves.
227 + self.met_again: set[int] = set()
228 + self.budget = 0
229 + # Shallowest thing the answers used since the last reset lean on.
230 + self.leans_on = _NOTHING
231 +
232 + def accepts(self, schema: t.Any) -> bool:
233 + if isinstance(schema, bool):
234 + return schema
235 + if not isinstance(schema, dict):
236 + return True
237 + key = id(schema)
238 + remembered = self.answers.get(key)
239 + if remembered is not None:
240 + if not self.path:
241 + return remembered[1] and remembered[2] != _A_BOUND
242 + self.leans_on = min(self.leans_on, remembered[2])
243 + return remembered[1]
244 + if key in self.path:
245 + self.met_again.add(self.path[key])
246 + self.leans_on = min(self.leans_on, self.path[key])
247 + return False
248 + depth = len(self.path)
249 + if depth == 0:
250 + self.budget = MAX_NULL_CHECK_NODES
251 + if depth >= MAX_NULL_CHECK_DEPTH or self.budget <= 0:
252 + self.leans_on = _A_BOUND
253 + return False
254 + self.budget -= 1
255 +
256 + outer, self.leans_on = self.leans_on, _NOTHING
257 + mark = len(self.provisional)
258 + self.path[key] = depth
259 + result = self._keywords_accept(schema)
260 + del self.path[key]
261 +
262 + leans_on = self.leans_on
263 + settled = leans_on >= depth
264 + below = self.provisional[mark:]
265 + del self.provisional[mark:]
266 + if result and depth in self.met_again:
267 + # The answers below took this node for rejecting null.
268 + for other in below:
269 + del self.answers[other]
270 + else:
271 + for other in below:
272 + node, answer, inner = self.answers[other]
273 + if settled:
274 + inner = _NOTHING
275 + else:
276 + inner = inner if inner < depth else leans_on
277 + self.provisional.append(other)
278 + self.answers[other] = (node, answer, inner)
279 + self.met_again.discard(depth)
280 +
281 + if depth == 0 and leans_on == _A_BOUND:
282 + result = False
283 + self.answers[key] = (schema, result, _NOTHING if settled else leans_on)
284 + if not settled:
285 + self.provisional.append(key)
286 + self.leans_on = outer if settled else min(outer, leans_on)
287 + if depth == 0:
288 + # Whatever is still provisional leans on a bound, and stays so.
289 + self.provisional.clear()
290 + self.leans_on = _NOTHING
291 + return result
292 +
293 + def _keywords_accept(self, node: dict[str, t.Any]) -> bool:
294 + accepts = self.accepts
295 + node_type = node.get("type")
296 + if isinstance(node_type, str) and node_type != "null":
297 + return False
298 + if isinstance(node_type, list) and "null" not in node_type:
299 + return False
300 + if (
301 + self.strict_output
302 + and "type" not in node
303 + and isinstance(node.get("properties"), dict)
304 + ):
305 + return False
306 + if isinstance(node.get("enum"), list) and None not in node["enum"]:
307 + return False
308 + if "const" in node and node["const"] is not None:
309 + return False
310 + if "$ref" in node:
311 + ref = node["$ref"]
312 + resolution = (
313 + _try_resolve_pointer(self.root, ref) if isinstance(ref, str) else None
314 + )
315 + if resolution is None or not resolution.ok:
316 + return False
317 + if not accepts(resolution.value):
318 + return False
319 + any_of, one_of, all_of = node.get("anyOf"), node.get("oneOf"), node.get("allOf")
320 + if isinstance(any_of, list) and not any(accepts(b) for b in any_of):
321 + return False
322 + if isinstance(one_of, list):
323 + matches = sum(accepts(b) for b in one_of)
324 + # The strict rewrite turns oneOf into anyOf.
325 + if matches == 0 or (matches > 1 and not self.strict_output):
326 + return False
327 + if isinstance(all_of, list) and not all(accepts(b) for b in all_of):
328 + return False
329 + if "not" in node and accepts(node["not"]):
330 + return False
331 + if "if" in node:
332 + branch = "then" if accepts(node["if"]) else "else"
333 + if branch in node and not accepts(node[branch]):
334 + return False
335 return True
171 - node_type = node.get("type")
172 - if isinstance(node_type, str):
173 - return node_type == "null"
174 - if isinstance(node_type, list):
175 - return "null" in node_type
176 - if isinstance(node.get("enum"), list):
177 - return None in node["enum"]
178 - if "const" in node:
179 - return node["const"] is None
180 - for keyword in ("anyOf", "oneOf"):
181 - branches = node.get(keyword)
182 - if isinstance(branches, list):
183 - return any(_schema_accepts_null(b, root) for b in branches)
184 - return True
336
337
338 def _dedupe_required(value: t.Any, is_schema: bool = True, depth: int = 0) -> t.Any:
@@ -210,6 +361,9 @@ class _Walker:
361 self.changes: list[StrictSchemaChange] = []
362 self.total_changes = 0
363 self.unsupported: list[StrictSchemaIncompatibility] = []
364 + self.null_check = _NullCheck(root, strict_output=True)
365 + # Resolved references, re-checked against the rewritten schema.
366 + self.references: list[tuple[str, str]] = []
367
368 def record(self, path: str, reason: StrictSchemaChangeReason, detail: str) -> None:
369 self.total_changes += 1
@@ -297,6 +451,8 @@ class _Walker:
451 ).ok
452 if not resolved:
453 self.reject(path, "$ref", f'unresolved $ref "{ref}"')
454 + else:
455 + self.references.append((path, ref))
456 # The referenced definition is normalized where it is declared.
457 return out
458
@@ -326,7 +482,7 @@ class _Walker:
482 continue
483 if name in declared_required or not isinstance(property_schema, dict):
484 continue
329 - properties[name] = _widen_to_nullable(property_schema)
485 + properties[name] = _widen_to_nullable(property_schema, self.null_check)
486 self.record(
487 _join_path(path, f"properties.{name}"),
488 "optional-property-nullable",
@@ -372,6 +528,11 @@ def to_strict_json_schema(schema: t.Any) -> StrictJsonSchemaResult:
528 root: dict[str, t.Any] = schema if isinstance(schema, dict) else {}
529 walker = _Walker(root)
530 normalized = _dedupe_required(walker.walk(root, "schema", 0, ""))
531 + if isinstance(normalized, dict):
532 + # Wrapping a property in a null branch moves everything nested in it.
533 + for path, ref in walker.references:
534 + if not _try_resolve_pointer(normalized, ref).ok:
535 + walker.reject(path, "$ref", f'$ref "{ref}" target moved by the rewrite')
536 if not isinstance(normalized, dict) or not _is_object_type(normalized.get("type")):
537 walker.reject("", "type", "root must be a non-nullable object")
538 return StrictJsonSchemaResult(
@@ -398,7 +559,9 @@ def omit_null_tool_arguments(
559 mutated.
560 """
561 root: dict[str, t.Any] = schema if isinstance(schema, dict) else {}
401 - return t.cast(dict[str, t.Any], _omit_nulls(arguments, root, root, 0))
562 + return t.cast(
563 + dict[str, t.Any], _omit_nulls(arguments, root, root, 0, _NullCheck(root))
564 + )
565
566
567 def _select_branch_for(
@@ -430,7 +593,11 @@ def _select_branch_for(
593
594
595 def _omit_nulls(
433 - value: t.Any, schema: t.Any, root: dict[str, t.Any], depth: int
596 + value: t.Any,
597 + schema: t.Any,
598 + root: dict[str, t.Any],
599 + depth: int,
600 + null_check: _NullCheck,
601 ) -> t.Any:
602 if depth > MAX_NODE_DEPTH:
603 raise ValueError(
@@ -439,7 +606,7 @@ def _omit_nulls(
606 node = _select_branch_for(schema, value, root) or {}
607 if isinstance(value, list):
608 items = node.get("items") if isinstance(node.get("items"), dict) else None
442 - return [_omit_nulls(item, items, root, depth + 1) for item in value]
609 + return [_omit_nulls(item, items, root, depth + 1, null_check) for item in value]
610 if not isinstance(value, dict):
611 return value
612 declared = node.get("properties")
@@ -448,8 +615,8 @@ def _omit_nulls(
615 for key, child in value.items():
616 property_schema = properties.get(key)
617 if child is None:
451 - if property_schema is None or _schema_accepts_null(property_schema, root):
618 + if property_schema is None or null_check.accepts(property_schema):
619 clone[key] = child
620 continue
454 - clone[key] = _omit_nulls(child, property_schema, root, depth + 1)
621 + clone[key] = _omit_nulls(child, property_schema, root, depth + 1, null_check)
622 return clone
python/tests/fixtures/json-schema-conversion/strict-cases.json
+478
@@ -2986,6 +2986,484 @@
2986 "output": {}
2987 }
2988 ]
2989 + },
2990 + {
2991 + "id": "optional-typed-enum-wrapped",
2992 + "description": "A typed enum is wrapped whole: adding null to its type would leave the enum rejecting it.",
2993 + "schema": {
2994 + "type": "object",
2995 + "properties": {
2996 + "direction": {
2997 + "type": "string",
2998 + "enum": ["asc", "desc"],
2999 + "description": "sort order"
3000 + }
3001 + }
3002 + },
3003 + "strict": {
3004 + "schema": {
3005 + "type": "object",
3006 + "properties": {
3007 + "direction": {
3008 + "description": "sort order",
3009 + "anyOf": [
3010 + {
3011 + "type": "string",
3012 + "enum": ["asc", "desc"]
3013 + },
3014 + {
3015 + "type": "null"
3016 + }
3017 + ]
3018 + }
3019 + },
3020 + "required": ["direction"],
3021 + "additionalProperties": false
3022 + }
3023 + },
3024 + "changes": [
3025 + {
3026 + "path": "properties.direction",
3027 + "reason": "optional-property-nullable"
3028 + }
3029 + ],
3030 + "arguments": [
3031 + {
3032 + "input": {
3033 + "direction": null
3034 + },
3035 + "output": {}
3036 + },
3037 + {
3038 + "input": {
3039 + "direction": "asc"
3040 + },
3041 + "output": {
3042 + "direction": "asc"
3043 + }
3044 + }
3045 + ]
3046 + },
3047 + {
3048 + "id": "optional-nullable-typed-enum-wrapped",
3049 + "description": "A null in `type` does not make an enum without null nullable.",
3050 + "schema": {
3051 + "type": "object",
3052 + "properties": {
3053 + "direction": {
3054 + "type": ["string", "null"],
3055 + "enum": ["asc", "desc"]
3056 + }
3057 + }
3058 + },
3059 + "strict": {
3060 + "schema": {
3061 + "type": "object",
3062 + "properties": {
3063 + "direction": {
3064 + "anyOf": [
3065 + {
3066 + "type": ["string", "null"],
3067 + "enum": ["asc", "desc"]
3068 + },
3069 + {
3070 + "type": "null"
3071 + }
3072 + ]
3073 + }
3074 + },
3075 + "required": ["direction"],
3076 + "additionalProperties": false
3077 + }
3078 + },
3079 + "changes": [
3080 + {
3081 + "path": "properties.direction",
3082 + "reason": "optional-property-nullable"
3083 + }
3084 + ],
3085 + "arguments": [
3086 + {
3087 + "input": {
3088 + "direction": null
3089 + },
3090 + "output": {}
3091 + }
3092 + ]
3093 + },
3094 + {
3095 + "id": "optional-typed-const-wrapped",
3096 + "description": "A typed const is wrapped whole, like a typed enum.",
3097 + "schema": {
3098 + "type": "object",
3099 + "properties": {
3100 + "mode": {
3101 + "type": "string",
3102 + "const": "asc"
3103 + }
3104 + }
3105 + },
3106 + "strict": {
3107 + "schema": {
3108 + "type": "object",
3109 + "properties": {
3110 + "mode": {
3111 + "anyOf": [
3112 + {
3113 + "type": "string",
3114 + "const": "asc"
3115 + },
3116 + {
3117 + "type": "null"
3118 + }
3119 + ]
3120 + }
3121 + },
3122 + "required": ["mode"],
3123 + "additionalProperties": false
3124 + }
3125 + },
3126 + "changes": [
3127 + {
3128 + "path": "properties.mode",
3129 + "reason": "optional-property-nullable"
3130 + }
3131 + ],
3132 + "arguments": [
3133 + {
3134 + "input": {
3135 + "mode": null
3136 + },
3137 + "output": {}
3138 + }
3139 + ]
3140 + },
3141 + {
3142 + "id": "optional-typed-enum-with-null-unchanged",
3143 + "description": "A typed enum that lists null under a nullable type already accepts null.",
3144 + "schema": {
3145 + "type": "object",
3146 + "properties": {
3147 + "direction": {
3148 + "type": ["string", "null"],
3149 + "enum": ["asc", null]
3150 + }
3151 + }
3152 + },
3153 + "strict": {
3154 + "schema": {
3155 + "type": "object",
3156 + "properties": {
3157 + "direction": {
3158 + "type": ["string", "null"],
3159 + "enum": ["asc", null]
3160 + }
3161 + },
3162 + "required": ["direction"],
3163 + "additionalProperties": false
3164 + }
3165 + },
3166 + "changes": [
3167 + {
3168 + "path": "properties.direction",
3169 + "reason": "optional-property-nullable"
3170 + }
3171 + ],
3172 + "arguments": [
3173 + {
3174 + "input": {
3175 + "direction": null
3176 + },
3177 + "output": {
3178 + "direction": null
3179 + }
3180 + }
3181 + ]
3182 + },
3183 + {
3184 + "id": "optional-any-of-with-sibling-enum-wrapped",
3185 + "description": "A null branch in anyOf does not lift a sibling enum, so the node is wrapped.",
3186 + "schema": {
3187 + "type": "object",
3188 + "properties": {
3189 + "direction": {
3190 + "enum": ["asc", "desc"],
3191 + "anyOf": [
3192 + {
3193 + "type": "string"
3194 + },
3195 + {
3196 + "type": "null"
3197 + }
3198 + ]
3199 + }
3200 + }
3201 + },
3202 + "strict": {
3203 + "schema": {
3204 + "type": "object",
3205 + "properties": {
3206 + "direction": {
3207 + "anyOf": [
3208 + {
3209 + "enum": ["asc", "desc"],
3210 + "anyOf": [
3211 + {
3212 + "type": "string"
3213 + },
3214 + {
3215 + "type": "null"
3216 + }
3217 + ]
3218 + },
3219 + {
3220 + "type": "null"
3221 + }
3222 + ]
3223 + }
3224 + },
3225 + "required": ["direction"],
3226 + "additionalProperties": false
3227 + }
3228 + },
3229 + "changes": [
3230 + {
3231 + "path": "properties.direction",
3232 + "reason": "optional-property-nullable"
3233 + }
3234 + ],
3235 + "arguments": [
3236 + {
3237 + "input": {
3238 + "direction": null
3239 + },
3240 + "output": {}
3241 + }
3242 + ]
3243 + },
3244 + {
3245 + "id": "optional-ref-with-sibling-type-wrapped",
3246 + "description": "Keywords beside a $ref apply together with its target.",
3247 + "schema": {
3248 + "type": "object",
3249 + "properties": {
3250 + "direction": {
3251 + "$ref": "#/$defs/Direction",
3252 + "type": "string"
3253 + }
3254 + },
3255 + "$defs": {
3256 + "Direction": {
3257 + "enum": ["asc", null]
3258 + }
3259 + }
3260 + },
3261 + "strict": {
3262 + "schema": {
3263 + "type": "object",
3264 + "properties": {
3265 + "direction": {
3266 + "anyOf": [
3267 + {
3268 + "$ref": "#/$defs/Direction",
3269 + "type": "string"
3270 + },
3271 + {
3272 + "type": "null"
3273 + }
3274 + ]
3275 + }
3276 + },
3277 + "$defs": {
3278 + "Direction": {
3279 + "enum": ["asc", null]
3280 + }
3281 + },
3282 + "required": ["direction"],
3283 + "additionalProperties": false
3284 + }
3285 + },
3286 + "changes": [
3287 + {
3288 + "path": "properties.direction",
3289 + "reason": "optional-property-nullable"
3290 + }
3291 + ],
3292 + "arguments": [
3293 + {
3294 + "input": {
3295 + "direction": null
3296 + },
3297 + "output": {}
3298 + }
3299 + ]
3300 + },
3301 + {
3302 + "id": "optional-ref-to-nullable-definition-unchanged",
3303 + "description": "A $ref whose target accepts null needs no extra null branch.",
3304 + "schema": {
3305 + "type": "object",
3306 + "properties": {
3307 + "note": {
3308 + "$ref": "#/$defs/Note"
3309 + }
3310 + },
3311 + "$defs": {
3312 + "Note": {
3313 + "type": ["string", "null"]
3314 + }
3315 + }
3316 + },
3317 + "strict": {
3318 + "schema": {
3319 + "type": "object",
3320 + "properties": {
3321 + "note": {
3322 + "$ref": "#/$defs/Note"
3323 + }
3324 + },
3325 + "$defs": {
3326 + "Note": {
3327 + "type": ["string", "null"]
3328 + }
3329 + },
3330 + "required": ["note"],
3331 + "additionalProperties": false
3332 + }
3333 + },
3334 + "changes": [
3335 + {
3336 + "path": "properties.note",
3337 + "reason": "optional-property-nullable"
3338 + }
3339 + ],
3340 + "arguments": [
3341 + {
3342 + "input": {
3343 + "note": null
3344 + },
3345 + "output": {
3346 + "note": null
3347 + }
3348 + }
3349 + ]
3350 + },
3351 + {
3352 + "id": "optional-ref-to-typeless-object-wrapped",
3353 + "description": "A definition with properties but no type is typed as an object by the rewrite, so a $ref to it needs a null branch.",
3354 + "schema": {
3355 + "type": "object",
3356 + "properties": {
3357 + "cfg": {
3358 + "$ref": "#/$defs/Config"
3359 + }
3360 + },
3361 + "$defs": {
3362 + "Config": {
3363 + "properties": {
3364 + "url": {
3365 + "type": "string"
3366 + }
3367 + },
3368 + "required": ["url"]
3369 + }
3370 + }
3371 + },
3372 + "strict": {
3373 + "schema": {
3374 + "type": "object",
3375 + "properties": {
3376 + "cfg": {
3377 + "anyOf": [
3378 + {
3379 + "$ref": "#/$defs/Config"
3380 + },
3381 + {
3382 + "type": "null"
3383 + }
3384 + ]
3385 + }
3386 + },
3387 + "$defs": {
3388 + "Config": {
3389 + "properties": {
3390 + "url": {
3391 + "type": "string"
3392 + }
3393 + },
3394 + "required": ["url"],
3395 + "type": "object",
3396 + "additionalProperties": false
3397 + }
3398 + },
3399 + "required": ["cfg"],
3400 + "additionalProperties": false
3401 + }
3402 + },
3403 + "changes": [
3404 + {
3405 + "path": "properties.cfg",
3406 + "reason": "optional-property-nullable"
3407 + }
3408 + ],
3409 + "arguments": [
3410 + {
3411 + "input": {
3412 + "cfg": null
3413 + },
3414 + "output": {
3415 + "cfg": null
3416 + }
3417 + },
3418 + {
3419 + "input": {
3420 + "cfg": {
3421 + "url": "u"
3422 + }
3423 + },
3424 + "output": {
3425 + "cfg": {
3426 + "url": "u"
3427 + }
3428 + }
3429 + }
3430 + ]
3431 + },
3432 + {
3433 + "id": "ref-into-wrapped-property-unsupported",
3434 + "description": "Wrapping a property moves what is nested in it; a $ref into it would dangle.",
3435 + "schema": {
3436 + "type": "object",
3437 + "properties": {
3438 + "value": {
3439 + "type": "string",
3440 + "enum": ["asc"],
3441 + "$defs": {
3442 + "Text": {
3443 + "type": "string"
3444 + }
3445 + }
3446 + },
3447 + "alias": {
3448 + "$ref": "#/properties/value/$defs/Text"
3449 + }
3450 + },
3451 + "required": ["alias"]
3452 + },
3453 + "strict": {
3454 + "unsupported": [
3455 + {
3456 + "path": "properties.alias",
3457 + "keyword": "$ref"
3458 + }
3459 + ]
3460 + },
3461 + "changes": [
3462 + {
3463 + "path": "properties.value",
3464 + "reason": "optional-property-nullable"
3465 + }
3466 + ]
3467 }
3468 ]
3469 }
python/tests/test_strict_schema.py
+331
@@ -657,3 +657,334 @@ class TestOpenAIResponsesProviderStrict:
657
658 assert received["slug"] == "TEST_TOOL"
659 assert received["arguments"] == {"cfg": {"url": "u"}, "clearable": None}
660 +
661 +
662 +NULL_BRANCH = {"type": "null"}
663 +DIRECTION = {"enum": ["asc", None]}
664 +
665 +
666 +def _wrapped(schema):
667 + return {"anyOf": [schema, NULL_BRANCH]}
668 +
669 +
670 +class TestNullAcceptance:
671 + """Null widening and null omission decide with every keyword, not the first."""
672 +
673 + @pytest.mark.parametrize(
674 + "property_schema, expected",
675 + [
676 + (
677 + {"type": "string", "enum": ["asc", "desc"]},
678 + _wrapped({"type": "string", "enum": ["asc", "desc"]}),
679 + ),
680 + (
681 + {"type": ["string", "null"], "enum": ["asc", "desc"]},
682 + _wrapped({"type": ["string", "null"], "enum": ["asc", "desc"]}),
683 + ),
684 + (
685 + {"type": "string", "const": "asc"},
686 + _wrapped({"type": "string", "const": "asc"}),
687 + ),
688 + (
689 + {"type": "integer", "enum": [1, 2], "description": "page size"},
690 + {
691 + "description": "page size",
692 + **_wrapped({"type": "integer", "enum": [1, 2]}),
693 + },
694 + ),
695 + (
696 + {"type": "string", "anyOf": [{"minLength": 1}]},
697 + _wrapped({"type": "string", "anyOf": [{"minLength": 1}]}),
698 + ),
699 + (
700 + {"enum": ["asc"], "anyOf": [{"type": "string"}, NULL_BRANCH]},
701 + _wrapped({"enum": ["asc"], "anyOf": [{"type": "string"}, NULL_BRANCH]}),
702 + ),
703 + (
704 + {"$ref": "#/$defs/Direction", "type": "string"},
705 + _wrapped({"$ref": "#/$defs/Direction", "type": "string"}),
706 + ),
707 + # Already nullable: left alone.
708 + (
709 + {"type": ["string", "null"], "enum": ["asc", None]},
710 + {"type": ["string", "null"], "enum": ["asc", None]},
711 + ),
712 + ({"$ref": "#/$defs/Direction"}, {"$ref": "#/$defs/Direction"}),
713 + (
714 + {"anyOf": [{"type": ["string", "null"]}]},
715 + {"anyOf": [{"type": ["string", "null"]}]},
716 + ),
717 + # `type` or `anyOf` as the only obstacle: widened in place.
718 + (
719 + {"type": "string", "minLength": 1},
720 + {"type": ["string", "null"], "minLength": 1},
721 + ),
722 + (
723 + {"anyOf": [{"type": "string"}], "description": "d"},
724 + {"anyOf": [{"type": "string"}, NULL_BRANCH], "description": "d"},
725 + ),
726 + ],
727 + )
728 + def test_widening_keeps_every_constraint(self, property_schema, expected):
729 + source = {
730 + "type": "object",
731 + "properties": {"value": property_schema},
732 + "$defs": {"Direction": DIRECTION},
733 + }
734 + snapshot = copy.deepcopy(source)
735 + result = to_strict_json_schema(source)
736 +
737 + assert result.unsupported == []
738 + assert result.schema["properties"]["value"] == expected
739 + assert result.schema["required"] == ["value"]
740 + assert source == snapshot
741 + again = to_strict_json_schema(result.schema)
742 + assert again.schema == result.schema
743 + assert again.changes == []
744 +
745 + @pytest.mark.parametrize(
746 + "property_schema, kept",
747 + [
748 + ({"type": ["string", "null"], "enum": ["asc", "desc"]}, False),
749 + ({"type": ["string", "null"], "const": "asc"}, False),
750 + ({"type": ["string", "null"], "enum": ["asc", None]}, True),
751 + ({"type": ["string", "null"], "const": None}, True),
752 + ({"$ref": "#/$defs/Direction"}, True),
753 + ({"$ref": "#/$defs/Direction", "type": "string"}, False),
754 + ({"$ref": "#/$defs/Direction", "enum": ["asc"]}, False),
755 + ({"$ref": "#/$defs/Missing"}, False),
756 + ({"$ref": 1}, False),
757 + ({"allOf": [{"type": ["string", "null"]}, {"enum": ["asc"]}]}, False),
758 + ({"allOf": [{"type": ["string", "null"]}, DIRECTION]}, True),
759 + ({"oneOf": [NULL_BRANCH, {"type": "string"}]}, True),
760 + ({"oneOf": [NULL_BRANCH, {"enum": [None]}]}, False),
761 + ({"not": NULL_BRANCH}, False),
762 + ({"not": {"type": "string"}}, True),
763 + ({"if": NULL_BRANCH, "then": {"type": "string"}}, False),
764 + ({"if": {"type": "string"}, "then": {"type": "string"}}, True),
765 + ({"if": {"type": "string"}, "else": {"type": "string"}}, False),
766 + (True, True),
767 + (False, False),
768 + ],
769 + )
770 + def test_null_is_kept_only_when_every_keyword_accepts_it(
771 + self, property_schema, kept
772 + ):
773 + schema = {
774 + "type": "object",
775 + "properties": {"value": property_schema},
776 + "$defs": {"Direction": DIRECTION},
777 + }
778 + arguments = {"value": None}
779 + expected = {"value": None} if kept else {}
780 + assert omit_null_tool_arguments(arguments, schema) == expected
781 + assert arguments == {"value": None}
782 +
783 + @pytest.mark.parametrize(
784 + "definitions, kept",
785 + [
786 + ({"a": {"$ref": "#/$defs/a"}}, False),
787 + ({"a": {"$ref": "#/$defs/b"}, "b": {"$ref": "#/$defs/a"}}, False),
788 + ({"a": {"anyOf": [{"$ref": "#/$defs/a"}]}}, False),
789 + ({"a": {"type": "null", "oneOf": [{"$ref": "#/$defs/a"}]}}, False),
790 + (
791 + {
792 + "a": {"anyOf": [{"$ref": "#/$defs/b"}]},
793 + "b": {"anyOf": [{"$ref": "#/$defs/a"}]},
794 + },
795 + False,
796 + ),
797 + ({"a": {"anyOf": [{"$ref": "#/$defs/a"}, NULL_BRANCH]}}, True),
798 + ({"a": {"oneOf": [{"$ref": "#/$defs/a"}, NULL_BRANCH]}}, True),
799 + ],
800 + )
801 + def test_reference_cycles_terminate(self, definitions, kept):
802 + schema = {
803 + "type": "object",
804 + "properties": {"value": {"$ref": "#/$defs/a"}},
805 + "$defs": definitions,
806 + }
807 + expected = {"value": None} if kept else {}
808 + assert omit_null_tool_arguments({"value": None}, schema) == expected
809 + assert to_strict_json_schema(schema).unsupported == []
810 +
811 + def test_a_node_reached_twice_outside_a_cycle_is_checked_each_time(self):
812 + shared = {"anyOf": [NULL_BRANCH]}
813 + schema = {
814 + "type": "object",
815 + "properties": {"value": {"allOf": [shared, shared]}},
816 + }
817 + assert omit_null_tool_arguments({"value": None}, schema) == {"value": None}
818 +
819 + @staticmethod
820 + def _diamond(levels, keyword, leaf):
821 + """``a0`` is the leaf; every ``a(i)`` references ``a(i-1)`` twice."""
822 + definitions = {"a0": leaf}
823 + for i in range(1, levels + 1):
824 + ref = {"$ref": f"#/$defs/a{i - 1}"}
825 + definitions[f"a{i}"] = {keyword: [ref, ref]}
826 + return {
827 + "type": "object",
828 + "properties": {"value": {"$ref": f"#/$defs/a{levels}"}},
829 + "$defs": definitions,
830 + }
831 +
832 + def test_a_definition_shared_by_many_branches_is_evaluated_once(self):
833 + rejecting = self._diamond(20, "anyOf", {"type": "string"})
834 + strict = to_strict_json_schema(rejecting).schema
835 + assert strict["properties"]["value"] == _wrapped({"$ref": "#/$defs/a20"})
836 + assert omit_null_tool_arguments({"value": None}, rejecting) == {}
837 +
838 + accepting = self._diamond(20, "allOf", NULL_BRANCH)
839 + assert omit_null_tool_arguments({"value": None}, accepting) == {"value": None}
840 +
841 + def test_stays_bounded_when_cycles_keep_answers_from_being_remembered(self):
842 + # Every level also points back at the top, so no answer below it is final.
843 + levels = 20
844 + top = {"$ref": f"#/$defs/a{levels}"}
845 + definitions = {"a0": {"type": "string"}}
846 + for i in range(1, levels + 1):
847 + ref = {"$ref": f"#/$defs/a{i - 1}"}
848 + definitions[f"a{i}"] = {"anyOf": [ref, ref, top]}
849 + schema = {"type": "object", "properties": {"value": top}, "$defs": definitions}
850 + assert omit_null_tool_arguments({"value": None}, schema) == {}
851 + strict = to_strict_json_schema(schema).schema
852 + assert strict["properties"]["value"] == _wrapped(top)
853 +
854 + def test_null_is_not_proven_through_a_reference_chain_past_the_depth_bound(self):
855 + definitions = {"a0": NULL_BRANCH}
856 + for i in range(1, 101):
857 + definitions[f"a{i}"] = {"$ref": f"#/$defs/a{i - 1}"}
858 +
859 + def schema(name):
860 + return {
861 + "type": "object",
862 + "properties": {"value": {"$ref": f"#/$defs/{name}"}},
863 + "$defs": definitions,
864 + }
865 +
866 + assert omit_null_tool_arguments({"value": None}, schema("a100")) == {}
867 + assert omit_null_tool_arguments({"value": None}, schema("a10")) == {
868 + "value": None
869 + }
870 +
871 + def test_ref_to_a_target_the_rewrite_types_as_an_object_gets_a_null_branch(self):
872 + source = {
873 + "type": "object",
874 + "properties": {"node": {"$ref": "#/$defs/Node"}},
875 + "$defs": {
876 + "Node": {
877 + "properties": {
878 + "label": {"type": "string"},
879 + "child": {"$ref": "#/$defs/Node"},
880 + }
881 + }
882 + },
883 + }
884 + result = to_strict_json_schema(source)
885 + node = result.schema["$defs"]["Node"]
886 +
887 + assert result.unsupported == []
888 + assert result.schema["properties"]["node"] == _wrapped({"$ref": "#/$defs/Node"})
889 + assert node["type"] == "object"
890 + assert node["properties"]["child"] == _wrapped({"$ref": "#/$defs/Node"})
891 + # The tool's own schema accepts the null, so it is forwarded.
892 + assert omit_null_tool_arguments({"node": None}, source) == {"node": None}
893 +
894 + def test_ref_into_a_property_that_wrapping_moved_is_reported(self):
895 + result = to_strict_json_schema(
896 + {
897 + "type": "object",
898 + "properties": {
899 + "value": {
900 + "type": "string",
901 + "enum": ["asc"],
902 + "$defs": {"Text": {"type": "string"}},
903 + },
904 + "alias": {"$ref": "#/properties/value/$defs/Text"},
905 + },
906 + "required": ["alias"],
907 + }
908 + )
909 + assert [(e.path, e.keyword) for e in result.unsupported] == [
910 + ("properties.alias", "$ref")
911 + ]
912 +
913 + def test_many_properties_share_what_was_learned_about_a_cyclic_definition(self):
914 + levels = 20
915 + top = f"#/$defs/a{levels}"
916 + definitions = {"a0": {"type": "string"}}
917 + for i in range(1, levels + 1):
918 + lower = f"#/$defs/a{i - 1}"
919 + definitions[f"a{i}"] = {
920 + "anyOf": [{"$ref": lower}, {"$ref": lower}, {"$ref": top}]
921 + }
922 + names = [f"p{i}" for i in range(400)]
923 + schema = {
924 + "type": "object",
925 + "properties": {name: {"$ref": top} for name in names},
926 + "$defs": definitions,
927 + }
928 + strict = to_strict_json_schema(schema).schema
929 + assert all(
930 + strict["properties"][name] == _wrapped({"$ref": top}) for name in names
931 + )
932 + assert omit_null_tool_arguments(dict.fromkeys(names), schema) == {}
933 +
934 + def test_a_check_that_runs_out_of_budget_does_not_affect_the_next_one(self):
935 + schema = {
936 + "type": "object",
937 + "properties": {
938 + "wide": {"anyOf": [{"type": "string"} for _ in range(5000)]},
939 + "note": {"type": ["string", "null"]},
940 + "same": {"anyOf": [{"type": "string"}, NULL_BRANCH]},
941 + },
942 + }
943 + arguments = {"wide": None, "note": None, "same": None}
944 + assert omit_null_tool_arguments(arguments, schema) == {
945 + "note": None,
946 + "same": None,
947 + }
948 + strict = to_strict_json_schema(schema).schema["properties"]
949 + assert strict["note"] == {"type": ["string", "null"]}
950 + assert strict["same"] == {"anyOf": [{"type": "string"}, NULL_BRANCH]}
951 +
952 + def test_a_check_that_meets_a_bound_proves_nothing(self):
953 + # Both branches accept null, so `oneOf` rejects it; the second is only
954 + # reachable past the depth bound and must not count as a rejection.
955 + definitions = {"a0": NULL_BRANCH}
956 + for i in range(1, 71):
957 + definitions[f"a{i}"] = {"$ref": f"#/$defs/a{i - 1}"}
958 + deep = {"$ref": "#/$defs/a70"}
959 + schema = {
960 + "type": "object",
961 + "properties": {
962 + "one": {"oneOf": [NULL_BRANCH, deep]},
963 + "negated": {"not": deep},
964 + "guarded": {"if": deep, "else": NULL_BRANCH},
965 + # Reaches a node the checks above left unproven.
966 + "later": {"not": {"$ref": "#/$defs/a69"}},
967 + },
968 + "$defs": definitions,
969 + }
970 + arguments = dict.fromkeys(schema["properties"])
971 + assert omit_null_tool_arguments(arguments, schema) == {}
972 +
973 + def test_an_unproven_definition_is_not_evaluated_again_for_each_property(self):
974 + # `top` is cyclic and wider than the budget, so nothing about it settles.
975 + definitions = {
976 + "top": {"anyOf": [{"$ref": f"#/$defs/b{i}"} for i in range(3000)]}
977 + }
978 + for i in range(3000):
979 + definitions[f"b{i}"] = {
980 + "anyOf": [{"$ref": "#/$defs/top"}, {"type": "string"}]
981 + }
982 + names = [f"p{i}" for i in range(2000)]
983 + schema = {
984 + "type": "object",
985 + "properties": {name: {"$ref": "#/$defs/top"} for name in names},
986 + "$defs": definitions,
987 + }
988 + assert omit_null_tool_arguments(dict.fromkeys(names), schema) == {}
989 + strict = to_strict_json_schema(schema).schema["properties"]
990 + assert all(strict[name] == _wrapped({"$ref": "#/$defs/top"}) for name in names)
python/tests/test_strict_schema_properties.py new
+222
@@ -0,0 +1,222 @@
1 +"""Property-based null semantics for strict mode.
2 +
3 +The oracle is the `jsonschema` Draft 2020-12 validator. Strict mode makes every
4 +optional parameter required and uses ``null`` to mean "omitted", so for every
5 +generated optional property:
6 +
7 +- the strict schema accepts ``null``
8 +- the arguments left after :func:`omit_null_tool_arguments` validate against
9 + the tool's own schema, and a ``null`` that schema accepts is kept
10 +- the strict schema accepts every non-null value the tool's schema accepts,
11 + and nothing more unless a ``oneOf`` was converted to ``anyOf``
12 +- the rewrite is idempotent
13 +
14 +The TypeScript counterpart is
15 +``ts/packages/core/test/utils/jsonSchema.strict.property.test.ts``; keep the
16 +generators and invariants aligned.
17 +
18 +Those generators never produce reference cycles: a cycle that consumes no input
19 +makes the oracle recurse forever. Cycles are checked separately against the
20 +least fixed point of the definitions, computed by plain iteration: a null is
21 +accepted only when a finite chain of branches proves it.
22 +"""
23 +
24 +import copy
25 +import typing as t
26 +
27 +from hypothesis import assume, given, settings
28 +from hypothesis import strategies as st
29 +from jsonschema import Draft202012Validator
30 +
31 +from composio.utils.strict_schema import omit_null_tool_arguments, to_strict_json_schema
32 +
33 +TYPES = ("string", "integer", "boolean", "null")
34 +LITERALS: tuple[t.Any, ...] = ("asc", "desc", 1, True, None)
35 +SAMPLES: tuple[t.Any, ...] = ("asc", "desc", "other", 1, 2, True, False)
36 +DEFINITIONS: dict[str, t.Any] = {
37 + "Direction": {"type": "string", "enum": ["asc", "desc"]},
38 + "NullableDirection": {"enum": ["asc", None]},
39 + "Text": {"type": "string"},
40 + "NullableText": {"type": ["string", "null"]},
41 + "Config": {"properties": {"url": {"type": "string"}}},
42 +}
43 +# The rewrite types this definition as an object, so the strict schema rejects
44 +# the non-object values the tool's schema lets through.
45 +TYPELESS_OBJECT_REF = "#/$defs/Config"
46 +# Compositions strict mode supports, and the ones only the tool's schema uses.
47 +STRICT_COMPOSITIONS = ("anyOf", "oneOf")
48 +ALL_COMPOSITIONS = (*STRICT_COMPOSITIONS, "allOf", "not", "if")
49 +
50 +
51 +@st.composite
52 +def property_schemas(
53 + draw: st.DrawFn, compositions: tuple[str, ...], depth: int = 0
54 +) -> dict[str, t.Any]:
55 + schema: dict[str, t.Any] = {}
56 + type_kind = draw(st.sampled_from(("none", "single", "list")))
57 + if type_kind == "single":
58 + schema["type"] = draw(st.sampled_from(TYPES))
59 + elif type_kind == "list":
60 + schema["type"] = draw(
61 + st.lists(st.sampled_from(TYPES), min_size=1, max_size=3, unique=True)
62 + )
63 + literal_kind = draw(st.sampled_from(("none", "none", "enum", "const")))
64 + if literal_kind == "enum":
65 + schema["enum"] = draw(
66 + st.lists(st.sampled_from(LITERALS), min_size=1, max_size=3, unique_by=repr)
67 + )
68 + elif literal_kind == "const":
69 + schema["const"] = draw(st.sampled_from(LITERALS))
70 + if draw(st.integers(0, 3)) == 0:
71 + schema["$ref"] = "#/$defs/" + draw(st.sampled_from(sorted(DEFINITIONS)))
72 + if draw(st.booleans()):
73 + schema["description"] = "a parameter"
74 +
75 + if depth >= 2:
76 + return schema
77 + nested = property_schemas(compositions, depth + 1)
78 + keyword = draw(st.sampled_from((None, None, *compositions)))
79 + if keyword in ("anyOf", "oneOf", "allOf"):
80 + schema[keyword] = draw(st.lists(nested, min_size=1, max_size=3))
81 + elif keyword == "not":
82 + schema["not"] = draw(nested)
83 + elif keyword == "if":
84 + schema["if"] = draw(nested)
85 + for branch in ("then", "else"):
86 + if draw(st.booleans()):
87 + schema[branch] = draw(nested)
88 + return schema
89 +
90 +
91 +def tool_schema(property_schema: dict[str, t.Any]) -> dict[str, t.Any]:
92 + return {
93 + "type": "object",
94 + "properties": {"value": property_schema},
95 + "$defs": copy.deepcopy(DEFINITIONS),
96 + }
97 +
98 +
99 +def mentions(node: t.Any, keyword: str, value: t.Any = None) -> bool:
100 + """Whether any node carries ``keyword`` (with ``value``, when given)."""
101 + if isinstance(node, list):
102 + return any(mentions(item, keyword, value) for item in node)
103 + if not isinstance(node, dict):
104 + return False
105 + if keyword in node and (value is None or node[keyword] == value):
106 + return True
107 + return any(mentions(child, keyword, value) for child in node.values())
108 +
109 +
110 +@settings(max_examples=500, deadline=None)
111 +@given(property_schemas(STRICT_COMPOSITIONS))
112 +def test_null_stands_for_omission_without_changing_other_values(
113 + property_schema: dict[str, t.Any],
114 +) -> None:
115 + source = tool_schema(property_schema)
116 + snapshot = copy.deepcopy(source)
117 + result = to_strict_json_schema(source)
118 + assert source == snapshot
119 + assume(not result.unsupported)
120 +
121 + original = Draft202012Validator(source)
122 + strict = Draft202012Validator(result.schema)
123 +
124 + assert strict.is_valid({"value": None})
125 + sent = omit_null_tool_arguments({"value": None}, result.source)
126 + assert original.is_valid(sent)
127 + assert sent == ({"value": None} if original.is_valid({"value": None}) else {})
128 +
129 + if not mentions(property_schema, "$ref", TYPELESS_OBJECT_REF):
130 + for sample in SAMPLES:
131 + arguments = {"value": sample}
132 + if original.is_valid(arguments):
133 + assert strict.is_valid(arguments)
134 + elif not mentions(property_schema, "oneOf"):
135 + assert not strict.is_valid(arguments)
136 +
137 + again = to_strict_json_schema(result.schema)
138 + assert again.schema == result.schema
139 + assert again.changes == []
140 +
141 +
142 +@settings(max_examples=500, deadline=None)
143 +@given(property_schemas(ALL_COMPOSITIONS))
144 +def test_null_is_kept_exactly_when_the_tool_schema_accepts_it(
145 + property_schema: dict[str, t.Any],
146 +) -> None:
147 + source = tool_schema(property_schema)
148 + accepted = Draft202012Validator(source).is_valid({"value": None})
149 + expected = {"value": None} if accepted else {}
150 + assert omit_null_tool_arguments({"value": None}, source) == expected
151 +
152 +
153 +LEAVES: tuple[dict[str, t.Any], ...] = ({"type": "null"}, {"type": "string"}, {})
154 +
155 +
156 +@st.composite
157 +def reference_graphs(draw: st.DrawFn) -> dict[str, dict[str, t.Any]]:
158 + """Definitions that reference each other freely, cycles included."""
159 + names = [f"d{index}" for index in range(draw(st.integers(1, 7)))]
160 + references = st.lists(
161 + st.sampled_from(names).map(lambda name: {"$ref": f"#/$defs/{name}"}),
162 + min_size=1,
163 + max_size=3,
164 + )
165 + definitions: dict[str, dict[str, t.Any]] = {}
166 + for name in names:
167 + kind = draw(st.sampled_from(("leaf", "anyOf", "anyOf", "allOf", "allOf")))
168 + if kind == "leaf":
169 + definitions[name] = dict(draw(st.sampled_from(LEAVES)))
170 + else:
171 + branches: list[dict[str, t.Any]] = draw(references)
172 + if draw(st.booleans()):
173 + branches.append(dict(draw(st.sampled_from(LEAVES))))
174 + definitions[name] = {kind: branches}
175 + return definitions
176 +
177 +
178 +def least_fixed_point(definitions: dict[str, dict[str, t.Any]]) -> dict[str, bool]:
179 + accepted = dict.fromkeys(definitions, False)
180 +
181 + def holds(node: dict[str, t.Any]) -> bool:
182 + if "$ref" in node:
183 + return accepted[node["$ref"].rsplit("/", 1)[1]]
184 + if "anyOf" in node:
185 + return any(holds(branch) for branch in node["anyOf"])
186 + if "allOf" in node:
187 + return all(holds(branch) for branch in node["allOf"])
188 + return node.get("type") != "string"
189 +
190 + changed = True
191 + while changed:
192 + changed = False
193 + for name, definition in definitions.items():
194 + if not accepted[name] and holds(definition):
195 + accepted[name] = changed = True
196 + return accepted
197 +
198 +
199 +@settings(max_examples=500, deadline=None)
200 +@given(reference_graphs())
201 +def test_cyclic_references_resolve_to_the_least_fixed_point(
202 + definitions: dict[str, dict[str, t.Any]],
203 +) -> None:
204 + source = {
205 + "type": "object",
206 + "properties": {name: {"$ref": f"#/$defs/{name}"} for name in definitions},
207 + "$defs": definitions,
208 + }
209 + expected = least_fixed_point(definitions)
210 + arguments = dict.fromkeys(definitions)
211 + kept = omit_null_tool_arguments(arguments, source)
212 + assert kept == {name: None for name in definitions if expected[name]}
213 +
214 + # `allOf` makes the tool unsupported, but its properties are still widened.
215 + result = to_strict_json_schema(source)
216 + for name in definitions:
217 + reference = {"$ref": f"#/$defs/{name}"}
218 + widened = result.schema["properties"][name]
219 + if expected[name]:
220 + assert widened == reference
221 + else:
222 + assert widened == {"anyOf": [reference, {"type": "null"}]}
ts/packages/core/package.json
+2
@@ -123,6 +123,8 @@
123 "@hono/node-server": "^2.1.1",
124 "@type-challenges/utils": "^0.1.1",
125 "@types/semver": "^7.8.0",
126 + "ajv": "^8.20.0",
127 + "fast-check": "^4.10.2",
128 "hono": "catalog:",
129 "tsdown": "catalog:",
130 "tsx": "catalog:",
ts/packages/core/src/utils/jsonSchema.ts
+191 -36
@@ -6,6 +6,9 @@ import { isPlainObject } from './modifiers/FileToolModifier.utils.neutral';
6
7 const MAX_REF_CHAIN_DEPTH = 100;
8 const MAX_NODE_DEPTH = 512;
9 +// Bounds on one null-acceptance check; past either, null is not proven accepted.
10 +const MAX_NULL_CHECK_DEPTH = 64;
11 +const MAX_NULL_CHECK_NODES = 2_000;
12 const CYCLE_BREAK_SENTINEL = { type: 'object', additionalProperties: true } as const;
13
14 /** Keywords whose value is a single subschema. */
@@ -603,27 +606,44 @@ function setOwn(target: Record<string, unknown>, key: string, value: unknown): v
606 }
607
608 /**
606 - * Widens a property schema so that `null` is an accepted value, without
607 - * placing `type` beside `anyOf` (the API rejects that combination).
609 + * The only keywords that can reject a `null` instance; every other keyword
610 + * constrains strings, numbers, arrays or objects and ignores `null`.
611 */
609 -function widenToNullable(node: Record<string, unknown>): Record<string, unknown> {
610 - if (Array.isArray(node.anyOf)) {
611 - const alreadyNullable = node.anyOf.some(
612 - branch => isPlainObject(branch) && branch.type === 'null'
613 - );
614 - return alreadyNullable ? node : { ...node, anyOf: [...node.anyOf, { type: 'null' }] };
615 - }
616 - if (typeof node.type === 'string') {
617 - return node.type === 'null' ? node : { ...node, type: [node.type, 'null'] };
612 +const NULL_CONSTRAINT_KEYWORDS = [
613 + 'type',
614 + 'enum',
615 + 'const',
616 + '$ref',
617 + 'anyOf',
618 + 'oneOf',
619 + 'allOf',
620 + 'not',
621 + 'if',
622 + 'then',
623 + 'else',
624 +] as const;
625 +
626 +/**
627 + * Widens a property schema so that `null` is an accepted value while keeping
628 + * every other constraint it declares. A node whose only obstacle is `type` or
629 + * `anyOf` is widened in place. Anything else is wrapped whole, because JSON
630 + * Schema keywords apply together: adding `null` to `type` does not lift a
631 + * sibling `enum`. `acceptsNull` must answer for the strict output.
632 + */
633 +function widenToNullable(
634 + node: Record<string, unknown>,
635 + acceptsNull: (schema: unknown) => boolean
636 +): Record<string, unknown> {
637 + if (acceptsNull(node)) return node;
638 + const constraints = NULL_CONSTRAINT_KEYWORDS.filter(key => key in node);
639 + if (constraints.length === 1 && constraints[0] === 'type') {
640 + const members = Array.isArray(node.type) ? node.type : [node.type];
641 + return { ...node, type: [...members, 'null'] };
642 }
619 - if (Array.isArray(node.type)) {
620 - return node.type.includes('null') ? node : { ...node, type: [...node.type, 'null'] };
643 + if (constraints.length === 1 && constraints[0] === 'anyOf' && Array.isArray(node.anyOf)) {
644 + return { ...node, anyOf: [...node.anyOf, { type: 'null' }] };
645 }
622 - if ((Array.isArray(node.enum) && node.enum.includes(null)) || node.const === null) return node;
623 - // No `type` at all: an empty schema already accepts null; anything else
624 - // (enum-only, const, composition) is wrapped so the annotation stays outside.
646 const { description, title, ...rest } = node;
626 - if (Object.keys(rest).length === 0) return node;
647 return {
648 ...(description !== undefined ? { description } : {}),
649 ...(title !== undefined ? { title } : {}),
@@ -646,19 +666,136 @@ function resolveLocalRefs(node: unknown, root: Record<string, unknown>): unknown
666 return current;
667 }
668
649 -/** Whether a schema node accepts `null` as an instance. */
650 -function schemaAcceptsNull(schema: unknown, root: Record<string, unknown>): boolean {
651 - const node = resolveLocalRefs(schema, root);
652 - if (!isPlainObject(node)) return true;
653 - if (typeof node.type === 'string') return node.type === 'null';
654 - if (Array.isArray(node.type)) return node.type.includes('null');
655 - if (Array.isArray(node.enum)) return node.enum.includes(null);
656 - if ('const' in node) return node.const === null;
657 - for (const keyword of ['anyOf', 'oneOf']) {
658 - const branches = node[keyword];
659 - if (Array.isArray(branches)) return branches.some(branch => schemaAcceptsNull(branch, root));
660 - }
661 - return true;
669 +/**
670 + * Creates the check for whether schemas of one document accept `null` as an
671 + * instance: every keyword in `NULL_CONSTRAINT_KEYWORDS` that is present must
672 + * accept it. This is the single definition of null acceptance; the strict
673 + * rewrite and `omitNullToolArguments` both decide with it.
674 + *
675 + * `strictOutput` answers for the schema `toStrictJsonSchema` emits instead of
676 + * the one it was given: the rewrite types every node that declares
677 + * `properties` as an object, so such a node stops accepting null.
678 + *
679 + * One check serves a whole document, and an answer is computed once per node.
680 + * A reference cycle never yields a null by itself, so a node met again while
681 + * it is being evaluated counts as rejecting. An answer that leans on that is
682 + * provisional until the node it leans on is done: it is kept if that node
683 + * does reject null and discarded otherwise.
684 + *
685 + * Each check is bounded in depth and in nodes visited. A check that meets a
686 + * bound proves nothing, so it rejects null whatever its other branches say,
687 + * which costs at most a redundant null branch or a dropped null. The nodes it
688 + * went through stay marked as unproven, so a later check that reaches one of
689 + * them neither repeats the work nor trusts the answer.
690 + */
691 +function createNullCheck(
692 + root: Record<string, unknown>,
693 + strictOutput = false
694 +): (schema: unknown) => boolean {
695 + // Markers for what an answer leans on, besides the depth of a node on the path.
696 + const NOTHING = MAX_NULL_CHECK_DEPTH + 1;
697 + const A_BOUND = -1;
698 + const answers = new Map<object, { answer: boolean; leansOn: number }>();
699 + // Nodes whose answer is provisional, oldest first.
700 + const provisional: object[] = [];
701 + // Nodes being evaluated, mapped to their depth on the current path.
702 + const path = new Map<object, number>();
703 + // Depths of the path nodes that were met again below themselves.
704 + const metAgain = new Set<number>();
705 + let budget = 0;
706 + // Shallowest thing the answers used since the last reset lean on.
707 + let leansOn = NOTHING;
708 +
709 + const accepts = (schema: unknown): boolean => {
710 + if (typeof schema === 'boolean') return schema;
711 + if (!isPlainObject(schema)) return true;
712 + const remembered = answers.get(schema);
713 + if (remembered !== undefined) {
714 + if (path.size === 0) return remembered.answer && remembered.leansOn !== A_BOUND;
715 + leansOn = Math.min(leansOn, remembered.leansOn);
716 + return remembered.answer;
717 + }
718 + const onPath = path.get(schema);
719 + if (onPath !== undefined) {
720 + metAgain.add(onPath);
721 + leansOn = Math.min(leansOn, onPath);
722 + return false;
723 + }
724 + const depth = path.size;
725 + if (depth === 0) budget = MAX_NULL_CHECK_NODES;
726 + if (depth >= MAX_NULL_CHECK_DEPTH || budget <= 0) {
727 + leansOn = A_BOUND;
728 + return false;
729 + }
730 + budget -= 1;
731 +
732 + const outer = leansOn;
733 + leansOn = NOTHING;
734 + const mark = provisional.length;
735 + path.set(schema, depth);
736 + let answer = keywordsAccept(schema);
737 + path.delete(schema);
738 +
739 + const own = leansOn;
740 + const settled = own >= depth;
741 + const below = provisional.splice(mark);
742 + if (answer && metAgain.has(depth)) {
743 + // The answers below took this node for rejecting null.
744 + for (const other of below) answers.delete(other);
745 + } else {
746 + for (const other of below) {
747 + const entry = answers.get(other);
748 + if (entry === undefined) continue;
749 + if (settled) {
750 + entry.leansOn = NOTHING;
751 + } else {
752 + if (entry.leansOn >= depth) entry.leansOn = own;
753 + provisional.push(other);
754 + }
755 + }
756 + }
757 + metAgain.delete(depth);
758 +
759 + if (depth === 0 && own === A_BOUND) answer = false;
760 + answers.set(schema, { answer, leansOn: settled ? NOTHING : own });
761 + if (!settled) provisional.push(schema);
762 + leansOn = settled ? outer : Math.min(outer, own);
763 + if (depth === 0) {
764 + // Whatever is still provisional leans on a bound, and stays so.
765 + provisional.length = 0;
766 + leansOn = NOTHING;
767 + }
768 + return answer;
769 + };
770 +
771 + const keywordsAccept = (node: Record<string, unknown>): boolean => {
772 + if (typeof node.type === 'string' && node.type !== 'null') return false;
773 + if (Array.isArray(node.type) && !node.type.includes('null')) return false;
774 + if (strictOutput && !('type' in node) && isPlainObject(node.properties)) return false;
775 + if (Array.isArray(node.enum) && !node.enum.includes(null)) return false;
776 + if ('const' in node && node.const !== null) return false;
777 + if ('$ref' in node) {
778 + const resolution =
779 + typeof node.$ref === 'string' ? tryResolvePointer(root, node.$ref) : undefined;
780 + if (resolution === undefined || resolution.kind === 'unresolved') return false;
781 + if (!accepts(resolution.value)) return false;
782 + }
783 + if (Array.isArray(node.anyOf) && !node.anyOf.some(accepts)) return false;
784 + if (Array.isArray(node.oneOf)) {
785 + const matches = node.oneOf.filter(accepts).length;
786 + // The strict rewrite turns oneOf into anyOf.
787 + if (matches === 0 || (matches > 1 && !strictOutput)) return false;
788 + }
789 + if (Array.isArray(node.allOf) && !node.allOf.every(accepts)) return false;
790 + if ('not' in node && accepts(node.not)) return false;
791 + if ('if' in node) {
792 + const branch = accepts(node.if) ? 'then' : 'else';
793 + if (branch in node && !accepts(node[branch])) return false;
794 + }
795 + return true;
796 + };
797 +
798 + return accepts;
799 }
800
801 /**
@@ -694,6 +831,8 @@ function schemaAcceptsNull(schema: unknown, root: Record<string, unknown>): bool
831 export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
832 const changes: StrictSchemaChange[] = [];
833 const unsupported: StrictSchemaIncompatibility[] = [];
834 + // Resolved references, re-checked against the rewritten schema.
835 + const references: { path: string; ref: string }[] = [];
836 let totalChanges = 0;
837 const recordChange = (change: StrictSchemaChange): void => {
838 totalChanges += 1;
@@ -701,6 +840,7 @@ export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
840 };
841
842 const root: Record<string, unknown> = isPlainObject(schema) ? schema : {};
843 + const acceptsNullInOutput = createNullCheck(root, true);
844
845 function walkChildren(
846 node: Record<string, unknown>,
@@ -805,6 +945,8 @@ export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
945 keyword: '$ref',
946 detail: `unresolved $ref "${node.$ref}"`,
947 });
948 + } else {
949 + references.push({ path, ref: node.$ref });
950 }
951 // The referenced definition is normalized where it is declared.
952 return out;
@@ -834,7 +976,7 @@ export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
976 continue;
977 }
978 if (declaredRequired.has(name) || !isPlainObject(propertySchema)) continue;
837 - setOwn(properties, name, widenToNullable(propertySchema));
979 + setOwn(properties, name, widenToNullable(propertySchema, acceptsNullInOutput));
980 recordChange({
981 path: joinPath(path, `properties.${name}`),
982 reason: 'optional-property-nullable',
@@ -874,6 +1016,18 @@ export function toStrictJsonSchema(schema: unknown): StrictJsonSchemaResult {
1016 }
1017
1018 const normalized = walk(root, 'schema', 0, '');
1019 + if (isPlainObject(normalized)) {
1020 + // Wrapping a property in a null branch moves everything nested in it.
1021 + for (const { path, ref } of references) {
1022 + if (tryResolvePointer(normalized, ref).kind === 'unresolved') {
1023 + unsupported.push({
1024 + path,
1025 + keyword: '$ref',
1026 + detail: `$ref "${ref}" target moved by the rewrite`,
1027 + });
1028 + }
1029 + }
1030 + }
1031 if (!isPlainObject(normalized) || !isObjectType(normalized.type)) {
1032 unsupported.push({
1033 path: '',
@@ -912,7 +1066,7 @@ export function omitNullToolArguments(
1066 schema: unknown
1067 ): Record<string, unknown> {
1068 const root: Record<string, unknown> = isPlainObject(schema) ? schema : {};
915 - return omitNulls(args, root, root, 0) as Record<string, unknown>;
1069 + return omitNulls(args, root, root, 0, createNullCheck(root)) as Record<string, unknown>;
1070 }
1071
1072 /**
@@ -949,7 +1103,8 @@ function omitNulls(
1103 value: unknown,
1104 schema: unknown,
1105 root: Record<string, unknown>,
952 - depth: number
1106 + depth: number,
1107 + acceptsNull: (schema: unknown) => boolean
1108 ): unknown {
1109 if (depth > MAX_NODE_DEPTH) {
1110 throw new RangeError(`Tool arguments exceed maximum nesting depth of ${MAX_NODE_DEPTH}`);
@@ -957,7 +1112,7 @@ function omitNulls(
1112 const node = selectBranchFor(schema, value, root);
1113 if (Array.isArray(value)) {
1114 const items = node && isPlainObject(node.items) ? node.items : undefined;
960 - return value.map(item => omitNulls(item, items, root, depth + 1));
1115 + return value.map(item => omitNulls(item, items, root, depth + 1, acceptsNull));
1116 }
1117 if (!isPlainObject(value)) return value;
1118
@@ -968,12 +1123,12 @@ function omitNulls(
1123 ? properties[key]
1124 : undefined;
1125 if (child === null) {
971 - if (propertySchema === undefined || schemaAcceptsNull(propertySchema, root)) {
1126 + if (propertySchema === undefined || acceptsNull(propertySchema)) {
1127 setOwn(clone, key, child);
1128 }
1129 continue;
1130 }
976 - setOwn(clone, key, omitNulls(child, propertySchema, root, depth + 1));
1131 + setOwn(clone, key, omitNulls(child, propertySchema, root, depth + 1, acceptsNull));
1132 }
1133 return clone;
1134 }
ts/packages/core/test/fixtures/json-schema-conversion/generate-strict-cases.mjs
+75
@@ -452,8 +452,83 @@ const cases = [
452 $defs: { Alias: { $ref: '#/$defs/Real' }, Real: obj({ x: { type: 'string' } }, ['x']) },
453 }),
454 ],
455 + [
456 + 'optional-typed-enum-wrapped',
457 + 'A typed enum is wrapped whole: adding null to its type would leave the enum rejecting it.',
458 + obj({ direction: { type: 'string', enum: ['asc', 'desc'], description: 'sort order' } }),
459 + ],
460 + [
461 + 'optional-nullable-typed-enum-wrapped',
462 + 'A null in `type` does not make an enum without null nullable.',
463 + obj({ direction: { type: ['string', 'null'], enum: ['asc', 'desc'] } }),
464 + ],
465 + [
466 + 'optional-typed-const-wrapped',
467 + 'A typed const is wrapped whole, like a typed enum.',
468 + obj({ mode: { type: 'string', const: 'asc' } }),
469 + ],
470 + [
471 + 'optional-typed-enum-with-null-unchanged',
472 + 'A typed enum that lists null under a nullable type already accepts null.',
473 + obj({ direction: { type: ['string', 'null'], enum: ['asc', null] } }),
474 + ],
475 + [
476 + 'optional-any-of-with-sibling-enum-wrapped',
477 + 'A null branch in anyOf does not lift a sibling enum, so the node is wrapped.',
478 + obj({ direction: { enum: ['asc', 'desc'], anyOf: [{ type: 'string' }, { type: 'null' }] } }),
479 + ],
480 + [
481 + 'optional-ref-with-sibling-type-wrapped',
482 + 'Keywords beside a $ref apply together with its target.',
483 + obj({ direction: { $ref: '#/$defs/Direction', type: 'string' } }, undefined, {
484 + $defs: { Direction: { enum: ['asc', null] } },
485 + }),
486 + ],
487 + [
488 + 'optional-ref-to-nullable-definition-unchanged',
489 + 'A $ref whose target accepts null needs no extra null branch.',
490 + obj({ note: { $ref: '#/$defs/Note' } }, undefined, {
491 + $defs: { Note: { type: ['string', 'null'] } },
492 + }),
493 + ],
494 + [
495 + 'optional-ref-to-typeless-object-wrapped',
496 + 'A definition with properties but no type is typed as an object by the rewrite, so a $ref to it needs a null branch.',
497 + obj({ cfg: { $ref: '#/$defs/Config' } }, undefined, {
498 + $defs: { Config: { properties: { url: { type: 'string' } }, required: ['url'] } },
499 + }),
500 + ],
501 + [
502 + 'ref-into-wrapped-property-unsupported',
503 + 'Wrapping a property moves what is nested in it; a $ref into it would dangle.',
504 + obj(
505 + {
506 + value: { type: 'string', enum: ['asc'], $defs: { Text: { type: 'string' } } },
507 + alias: { $ref: '#/properties/value/$defs/Text' },
508 + },
509 + ['alias']
510 + ),
511 + ],
512 ];
513 const argumentCases = {
514 + 'optional-ref-to-typeless-object-wrapped': [
515 + { input: { cfg: null }, output: { cfg: null } },
516 + { input: { cfg: { url: 'u' } }, output: { cfg: { url: 'u' } } },
517 + ],
518 + 'optional-typed-enum-wrapped': [
519 + { input: { direction: null }, output: {} },
520 + { input: { direction: 'asc' }, output: { direction: 'asc' } },
521 + ],
522 + 'optional-nullable-typed-enum-wrapped': [{ input: { direction: null }, output: {} }],
523 + 'optional-typed-const-wrapped': [{ input: { mode: null }, output: {} }],
524 + 'optional-typed-enum-with-null-unchanged': [
525 + { input: { direction: null }, output: { direction: null } },
526 + ],
527 + 'optional-any-of-with-sibling-enum-wrapped': [{ input: { direction: null }, output: {} }],
528 + 'optional-ref-with-sibling-type-wrapped': [{ input: { direction: null }, output: {} }],
529 + 'optional-ref-to-nullable-definition-unchanged': [
530 + { input: { note: null }, output: { note: null } },
531 + ],
532 'nested-optional-property-widened': [
533 { input: { cfg: { url: 'u', note: null } }, output: { cfg: { url: 'u' } } },
534 ],
ts/packages/core/test/fixtures/json-schema-conversion/strict-cases.json
+478
@@ -2986,6 +2986,484 @@
2986 "output": {}
2987 }
2988 ]
2989 + },
2990 + {
2991 + "id": "optional-typed-enum-wrapped",
2992 + "description": "A typed enum is wrapped whole: adding null to its type would leave the enum rejecting it.",
2993 + "schema": {
2994 + "type": "object",
2995 + "properties": {
2996 + "direction": {
2997 + "type": "string",
2998 + "enum": ["asc", "desc"],
2999 + "description": "sort order"
3000 + }
3001 + }
3002 + },
3003 + "strict": {
3004 + "schema": {
3005 + "type": "object",
3006 + "properties": {
3007 + "direction": {
3008 + "description": "sort order",
3009 + "anyOf": [
3010 + {
3011 + "type": "string",
3012 + "enum": ["asc", "desc"]
3013 + },
3014 + {
3015 + "type": "null"
3016 + }
3017 + ]
3018 + }
3019 + },
3020 + "required": ["direction"],
3021 + "additionalProperties": false
3022 + }
3023 + },
3024 + "changes": [
3025 + {
3026 + "path": "properties.direction",
3027 + "reason": "optional-property-nullable"
3028 + }
3029 + ],
3030 + "arguments": [
3031 + {
3032 + "input": {
3033 + "direction": null
3034 + },
3035 + "output": {}
3036 + },
3037 + {
3038 + "input": {
3039 + "direction": "asc"
3040 + },
3041 + "output": {
3042 + "direction": "asc"
3043 + }
3044 + }
3045 + ]
3046 + },
3047 + {
3048 + "id": "optional-nullable-typed-enum-wrapped",
3049 + "description": "A null in `type` does not make an enum without null nullable.",
3050 + "schema": {
3051 + "type": "object",
3052 + "properties": {
3053 + "direction": {
3054 + "type": ["string", "null"],
3055 + "enum": ["asc", "desc"]
3056 + }
3057 + }
3058 + },
3059 + "strict": {
3060 + "schema": {
3061 + "type": "object",
3062 + "properties": {
3063 + "direction": {
3064 + "anyOf": [
3065 + {
3066 + "type": ["string", "null"],
3067 + "enum": ["asc", "desc"]
3068 + },
3069 + {
3070 + "type": "null"
3071 + }
3072 + ]
3073 + }
3074 + },
3075 + "required": ["direction"],
3076 + "additionalProperties": false
3077 + }
3078 + },
3079 + "changes": [
3080 + {
3081 + "path": "properties.direction",
3082 + "reason": "optional-property-nullable"
3083 + }
3084 + ],
3085 + "arguments": [
3086 + {
3087 + "input": {
3088 + "direction": null
3089 + },
3090 + "output": {}
3091 + }
3092 + ]
3093 + },
3094 + {
3095 + "id": "optional-typed-const-wrapped",
3096 + "description": "A typed const is wrapped whole, like a typed enum.",
3097 + "schema": {
3098 + "type": "object",
3099 + "properties": {
3100 + "mode": {
3101 + "type": "string",
3102 + "const": "asc"
3103 + }
3104 + }
3105 + },
3106 + "strict": {
3107 + "schema": {
3108 + "type": "object",
3109 + "properties": {
3110 + "mode": {
3111 + "anyOf": [
3112 + {
3113 + "type": "string",
3114 + "const": "asc"
3115 + },
3116 + {
3117 + "type": "null"
3118 + }
3119 + ]
3120 + }
3121 + },
3122 + "required": ["mode"],
3123 + "additionalProperties": false
3124 + }
3125 + },
3126 + "changes": [
3127 + {
3128 + "path": "properties.mode",
3129 + "reason": "optional-property-nullable"
3130 + }
3131 + ],
3132 + "arguments": [
3133 + {
3134 + "input": {
3135 + "mode": null
3136 + },
3137 + "output": {}
3138 + }
3139 + ]
3140 + },
3141 + {
3142 + "id": "optional-typed-enum-with-null-unchanged",
3143 + "description": "A typed enum that lists null under a nullable type already accepts null.",
3144 + "schema": {
3145 + "type": "object",
3146 + "properties": {
3147 + "direction": {
3148 + "type": ["string", "null"],
3149 + "enum": ["asc", null]
3150 + }
3151 + }
3152 + },
3153 + "strict": {
3154 + "schema": {
3155 + "type": "object",
3156 + "properties": {
3157 + "direction": {
3158 + "type": ["string", "null"],
3159 + "enum": ["asc", null]
3160 + }
3161 + },
3162 + "required": ["direction"],
3163 + "additionalProperties": false
3164 + }
3165 + },
3166 + "changes": [
3167 + {
3168 + "path": "properties.direction",
3169 + "reason": "optional-property-nullable"
3170 + }
3171 + ],
3172 + "arguments": [
3173 + {
3174 + "input": {
3175 + "direction": null
3176 + },
3177 + "output": {
3178 + "direction": null
3179 + }
3180 + }
3181 + ]
3182 + },
3183 + {
3184 + "id": "optional-any-of-with-sibling-enum-wrapped",
3185 + "description": "A null branch in anyOf does not lift a sibling enum, so the node is wrapped.",
3186 + "schema": {
3187 + "type": "object",
3188 + "properties": {
3189 + "direction": {
3190 + "enum": ["asc", "desc"],
3191 + "anyOf": [
3192 + {
3193 + "type": "string"
3194 + },
3195 + {
3196 + "type": "null"
3197 + }
3198 + ]
3199 + }
3200 + }
3201 + },
3202 + "strict": {
3203 + "schema": {
3204 + "type": "object",
3205 + "properties": {
3206 + "direction": {
3207 + "anyOf": [
3208 + {
3209 + "enum": ["asc", "desc"],
3210 + "anyOf": [
3211 + {
3212 + "type": "string"
3213 + },
3214 + {
3215 + "type": "null"
3216 + }
3217 + ]
3218 + },
3219 + {
3220 + "type": "null"
3221 + }
3222 + ]
3223 + }
3224 + },
3225 + "required": ["direction"],
3226 + "additionalProperties": false
3227 + }
3228 + },
3229 + "changes": [
3230 + {
3231 + "path": "properties.direction",
3232 + "reason": "optional-property-nullable"
3233 + }
3234 + ],
3235 + "arguments": [
3236 + {
3237 + "input": {
3238 + "direction": null
3239 + },
3240 + "output": {}
3241 + }
3242 + ]
3243 + },
3244 + {
3245 + "id": "optional-ref-with-sibling-type-wrapped",
3246 + "description": "Keywords beside a $ref apply together with its target.",
3247 + "schema": {
3248 + "type": "object",
3249 + "properties": {
3250 + "direction": {
3251 + "$ref": "#/$defs/Direction",
3252 + "type": "string"
3253 + }
3254 + },
3255 + "$defs": {
3256 + "Direction": {
3257 + "enum": ["asc", null]
3258 + }
3259 + }
3260 + },
3261 + "strict": {
3262 + "schema": {
3263 + "type": "object",
3264 + "properties": {
3265 + "direction": {
3266 + "anyOf": [
3267 + {
3268 + "$ref": "#/$defs/Direction",
3269 + "type": "string"
3270 + },
3271 + {
3272 + "type": "null"
3273 + }
3274 + ]
3275 + }
3276 + },
3277 + "$defs": {
3278 + "Direction": {
3279 + "enum": ["asc", null]
3280 + }
3281 + },
3282 + "required": ["direction"],
3283 + "additionalProperties": false
3284 + }
3285 + },
3286 + "changes": [
3287 + {
3288 + "path": "properties.direction",
3289 + "reason": "optional-property-nullable"
3290 + }
3291 + ],
3292 + "arguments": [
3293 + {
3294 + "input": {
3295 + "direction": null
3296 + },
3297 + "output": {}
3298 + }
3299 + ]
3300 + },
3301 + {
3302 + "id": "optional-ref-to-nullable-definition-unchanged",
3303 + "description": "A $ref whose target accepts null needs no extra null branch.",
3304 + "schema": {
3305 + "type": "object",
3306 + "properties": {
3307 + "note": {
3308 + "$ref": "#/$defs/Note"
3309 + }
3310 + },
3311 + "$defs": {
3312 + "Note": {
3313 + "type": ["string", "null"]
3314 + }
3315 + }
3316 + },
3317 + "strict": {
3318 + "schema": {
3319 + "type": "object",
3320 + "properties": {
3321 + "note": {
3322 + "$ref": "#/$defs/Note"
3323 + }
3324 + },
3325 + "$defs": {
3326 + "Note": {
3327 + "type": ["string", "null"]
3328 + }
3329 + },
3330 + "required": ["note"],
3331 + "additionalProperties": false
3332 + }
3333 + },
3334 + "changes": [
3335 + {
3336 + "path": "properties.note",
3337 + "reason": "optional-property-nullable"
3338 + }
3339 + ],
3340 + "arguments": [
3341 + {
3342 + "input": {
3343 + "note": null
3344 + },
3345 + "output": {
3346 + "note": null
3347 + }
3348 + }
3349 + ]
3350 + },
3351 + {
3352 + "id": "optional-ref-to-typeless-object-wrapped",
3353 + "description": "A definition with properties but no type is typed as an object by the rewrite, so a $ref to it needs a null branch.",
3354 + "schema": {
3355 + "type": "object",
3356 + "properties": {
3357 + "cfg": {
3358 + "$ref": "#/$defs/Config"
3359 + }
3360 + },
3361 + "$defs": {
3362 + "Config": {
3363 + "properties": {
3364 + "url": {
3365 + "type": "string"
3366 + }
3367 + },
3368 + "required": ["url"]
3369 + }
3370 + }
3371 + },
3372 + "strict": {
3373 + "schema": {
3374 + "type": "object",
3375 + "properties": {
3376 + "cfg": {
3377 + "anyOf": [
3378 + {
3379 + "$ref": "#/$defs/Config"
3380 + },
3381 + {
3382 + "type": "null"
3383 + }
3384 + ]
3385 + }
3386 + },
3387 + "$defs": {
3388 + "Config": {
3389 + "properties": {
3390 + "url": {
3391 + "type": "string"
3392 + }
3393 + },
3394 + "required": ["url"],
3395 + "type": "object",
3396 + "additionalProperties": false
3397 + }
3398 + },
3399 + "required": ["cfg"],
3400 + "additionalProperties": false
3401 + }
3402 + },
3403 + "changes": [
3404 + {
3405 + "path": "properties.cfg",
3406 + "reason": "optional-property-nullable"
3407 + }
3408 + ],
3409 + "arguments": [
3410 + {
3411 + "input": {
3412 + "cfg": null
3413 + },
3414 + "output": {
3415 + "cfg": null
3416 + }
3417 + },
3418 + {
3419 + "input": {
3420 + "cfg": {
3421 + "url": "u"
3422 + }
3423 + },
3424 + "output": {
3425 + "cfg": {
3426 + "url": "u"
3427 + }
3428 + }
3429 + }
3430 + ]
3431 + },
3432 + {
3433 + "id": "ref-into-wrapped-property-unsupported",
3434 + "description": "Wrapping a property moves what is nested in it; a $ref into it would dangle.",
3435 + "schema": {
3436 + "type": "object",
3437 + "properties": {
3438 + "value": {
3439 + "type": "string",
3440 + "enum": ["asc"],
3441 + "$defs": {
3442 + "Text": {
3443 + "type": "string"
3444 + }
3445 + }
3446 + },
3447 + "alias": {
3448 + "$ref": "#/properties/value/$defs/Text"
3449 + }
3450 + },
3451 + "required": ["alias"]
3452 + },
3453 + "strict": {
3454 + "unsupported": [
3455 + {
3456 + "path": "properties.alias",
3457 + "keyword": "$ref"
3458 + }
3459 + ]
3460 + },
3461 + "changes": [
3462 + {
3463 + "path": "properties.value",
3464 + "reason": "optional-property-nullable"
3465 + }
3466 + ]
3467 }
3468 ]
3469 }
ts/packages/core/test/utils/jsonSchema.strict.property.test.ts new
+246
@@ -0,0 +1,246 @@
1 +/**
2 + * Property-based null semantics for strict mode.
3 + *
4 + * The oracle is Ajv in Draft 2020-12 mode. Strict mode makes every optional
5 + * parameter required and uses `null` to mean "omitted", so for every generated
6 + * optional property:
7 + *
8 + * - the strict schema accepts `null`
9 + * - the arguments left after `omitNullToolArguments` validate against the
10 + * tool's own schema, and a `null` that schema accepts is kept
11 + * - the strict schema accepts every non-null value the tool's schema accepts,
12 + * and nothing more unless a `oneOf` was converted to `anyOf`
13 + * - the rewrite is idempotent
14 + *
15 + * The Python counterpart is `python/tests/test_strict_schema_properties.py`;
16 + * keep the generators and invariants aligned.
17 + *
18 + * Those generators never produce reference cycles: a cycle that consumes no
19 + * input makes the oracle recurse forever. Cycles are checked separately against
20 + * the least fixed point of the definitions, computed by plain iteration: a null
21 + * is accepted only when a finite chain of branches proves it.
22 + */
23 +import Ajv2020 from 'ajv/dist/2020';
24 +import fc from 'fast-check';
25 +import { describe, expect, it } from 'vitest';
26 +
27 +import { omitNullToolArguments, toStrictJsonSchema } from '../../src/utils/jsonSchema';
28 +
29 +type SchemaRecord = Record<string, unknown>;
30 +
31 +const TYPES = ['string', 'integer', 'boolean', 'null'] as const;
32 +const LITERALS = ['asc', 'desc', 1, true, null] as const;
33 +const SAMPLES = ['asc', 'desc', 'other', 1, 2, true, false] as const;
34 +const DEFINITIONS: SchemaRecord = {
35 + Direction: { type: 'string', enum: ['asc', 'desc'] },
36 + NullableDirection: { enum: ['asc', null] },
37 + Text: { type: 'string' },
38 + NullableText: { type: ['string', 'null'] },
39 + Config: { properties: { url: { type: 'string' } } },
40 +};
41 +// The rewrite types this definition as an object, so the strict schema rejects
42 +// the non-object values the tool's schema lets through.
43 +const TYPELESS_OBJECT_REF = '#/$defs/Config';
44 +// Compositions strict mode supports, and the ones only the tool's schema uses.
45 +const STRICT_COMPOSITIONS = ['anyOf', 'oneOf'] as const;
46 +const ALL_COMPOSITIONS = [...STRICT_COMPOSITIONS, 'allOf', 'not', 'if'] as const;
47 +type Composition = (typeof ALL_COMPOSITIONS)[number];
48 +
49 +const leafKeywords: fc.Arbitrary<SchemaRecord> = fc
50 + .record({
51 + type: fc.oneof(
52 + fc.constant(undefined),
53 + fc.constantFrom(...TYPES),
54 + fc.uniqueArray(fc.constantFrom(...TYPES), { minLength: 1, maxLength: 3 })
55 + ),
56 + literal: fc.oneof(
57 + { arbitrary: fc.constant<SchemaRecord>({}), weight: 2 },
58 + fc
59 + .uniqueArray(fc.constantFrom(...LITERALS), { minLength: 1, maxLength: 3 })
60 + .map(values => ({ enum: values })),
61 + fc.constantFrom(...LITERALS).map(value => ({ const: value }))
62 + ),
63 + ref: fc.oneof(
64 + { arbitrary: fc.constant(undefined), weight: 3 },
65 + fc.constantFrom(...Object.keys(DEFINITIONS)).map(name => `#/$defs/${name}`)
66 + ),
67 + described: fc.boolean(),
68 + })
69 + .map(({ type, literal, ref, described }) => ({
70 + ...(type === undefined ? {} : { type }),
71 + ...literal,
72 + ...(ref === undefined ? {} : { $ref: ref }),
73 + ...(described ? { description: 'a parameter' } : {}),
74 + }));
75 +
76 +function propertySchema(
77 + compositions: readonly Composition[],
78 + depth = 0
79 +): fc.Arbitrary<SchemaRecord> {
80 + if (depth >= 2) return leafKeywords;
81 + const nested = propertySchema(compositions, depth + 1);
82 + const branches = fc.array(nested, { minLength: 1, maxLength: 3 });
83 + const composition: Record<Composition, fc.Arbitrary<SchemaRecord>> = {
84 + anyOf: branches.map(anyOf => ({ anyOf })),
85 + oneOf: branches.map(oneOf => ({ oneOf })),
86 + allOf: branches.map(allOf => ({ allOf })),
87 + not: nested.map(not => ({ not })),
88 + if: fc
89 + .record({ if: nested, then: fc.option(nested), else: fc.option(nested) })
90 + .map(({ if: condition, then, else: otherwise }) => ({
91 + if: condition,
92 + ...(then === null ? {} : { then }),
93 + ...(otherwise === null ? {} : { else: otherwise }),
94 + })),
95 + };
96 + return fc
97 + .tuple(
98 + leafKeywords,
99 + fc.oneof(
100 + { arbitrary: fc.constant<SchemaRecord>({}), weight: 2 },
101 + ...compositions.map(keyword => composition[keyword])
102 + )
103 + )
104 + .map(([leaf, composed]) => ({ ...leaf, ...composed }));
105 +}
106 +
107 +const toolSchema = (property: SchemaRecord): SchemaRecord => ({
108 + type: 'object',
109 + properties: { value: property },
110 + $defs: structuredClone(DEFINITIONS),
111 +});
112 +
113 +/** Whether any node carries `keyword` (with `value`, when given). */
114 +const mentions = (node: unknown, keyword: string, value?: unknown): boolean => {
115 + if (Array.isArray(node)) return node.some(item => mentions(item, keyword, value));
116 + if (typeof node !== 'object' || node === null) return false;
117 + const record = node as SchemaRecord;
118 + if (keyword in record && (value === undefined || record[keyword] === value)) return true;
119 + return Object.values(record).some(child => mentions(child, keyword, value));
120 +};
121 +
122 +const ajv = new Ajv2020({ strict: false });
123 +const validatorFor = (schema: SchemaRecord) => ajv.compile(schema);
124 +const RUNS = 300;
125 +const TIMEOUT_MS = 30_000;
126 +
127 +const LEAVES: readonly SchemaRecord[] = [{ type: 'null' }, { type: 'string' }, {}];
128 +const leaf = fc.constantFrom(...LEAVES).map(schema => ({ ...schema }));
129 +
130 +/** Definitions that reference each other freely, cycles included. */
131 +const referenceGraph: fc.Arbitrary<Record<string, SchemaRecord>> = fc
132 + .integer({ min: 1, max: 7 })
133 + .chain(count => {
134 + const names = Array.from({ length: count }, (_, index) => `d${index}`);
135 + const reference = fc.constantFrom(...names).map(name => ({ $ref: `#/$defs/${name}` }));
136 + const composed = fc
137 + .record({
138 + keyword: fc.constantFrom('anyOf', 'allOf'),
139 + references: fc.array(reference, { minLength: 1, maxLength: 3 }),
140 + extra: fc.option(leaf),
141 + })
142 + .map(({ keyword, references, extra }) => ({
143 + [keyword]: extra === null ? references : [...references, extra],
144 + }));
145 + const definition = fc.oneof({ arbitrary: leaf, weight: 1 }, { arbitrary: composed, weight: 4 });
146 + return fc
147 + .tuple(...names.map(() => definition))
148 + .map(definitions =>
149 + Object.fromEntries(names.map((name, index) => [name, definitions[index]]))
150 + );
151 + });
152 +
153 +function leastFixedPoint(definitions: Record<string, SchemaRecord>): Record<string, boolean> {
154 + const accepted: Record<string, boolean> = Object.fromEntries(
155 + Object.keys(definitions).map(name => [name, false])
156 + );
157 + const holds = (node: SchemaRecord): boolean => {
158 + if (typeof node.$ref === 'string') return accepted[node.$ref.slice('#/$defs/'.length)];
159 + if (Array.isArray(node.anyOf)) return node.anyOf.some(holds);
160 + if (Array.isArray(node.allOf)) return node.allOf.every(holds);
161 + return node.type !== 'string';
162 + };
163 + for (let changed = true; changed;) {
164 + changed = false;
165 + for (const [name, definition] of Object.entries(definitions)) {
166 + if (!accepted[name] && holds(definition)) accepted[name] = changed = true;
167 + }
168 + }
169 + return accepted;
170 +}
171 +
172 +describe('strict-mode null semantics', () => {
173 + it('cyclic references resolve to the least fixed point', { timeout: TIMEOUT_MS }, () => {
174 + fc.assert(
175 + fc.property(referenceGraph, definitions => {
176 + const names = Object.keys(definitions);
177 + const reference = (name: string) => ({ $ref: `#/$defs/${name}` });
178 + const source = {
179 + type: 'object',
180 + properties: Object.fromEntries(names.map(name => [name, reference(name)])),
181 + $defs: definitions,
182 + };
183 + const expected = leastFixedPoint(definitions);
184 + const input = Object.fromEntries(names.map(name => [name, null]));
185 + expect(omitNullToolArguments(input, source)).toEqual(
186 + Object.fromEntries(names.filter(name => expected[name]).map(name => [name, null]))
187 + );
188 +
189 + // `allOf` makes the tool unsupported, but its properties are still widened.
190 + const properties = toStrictJsonSchema(source).schema.properties as SchemaRecord;
191 + for (const name of names) {
192 + expect(properties[name]).toEqual(
193 + expected[name] ? reference(name) : { anyOf: [reference(name), { type: 'null' }] }
194 + );
195 + }
196 + }),
197 + { numRuns: RUNS }
198 + );
199 + });
200 +
201 + it('null stands for omission without changing other values', { timeout: TIMEOUT_MS }, () => {
202 + fc.assert(
203 + fc.property(propertySchema(STRICT_COMPOSITIONS), property => {
204 + const source = toolSchema(property);
205 + const snapshot = structuredClone(source);
206 + const result = toStrictJsonSchema(source);
207 + expect(source).toEqual(snapshot);
208 + fc.pre(result.unsupported.length === 0);
209 +
210 + const original = validatorFor(source);
211 + const strict = validatorFor(result.schema);
212 +
213 + expect(strict({ value: null })).toBe(true);
214 + const sent = omitNullToolArguments({ value: null }, result.source);
215 + expect(original(sent)).toBe(true);
216 + expect(sent).toEqual(original({ value: null }) ? { value: null } : {});
217 +
218 + if (!mentions(property, '$ref', TYPELESS_OBJECT_REF)) {
219 + for (const sample of SAMPLES) {
220 + const args = { value: sample };
221 + if (original(args)) expect(strict(args)).toBe(true);
222 + else if (!mentions(property, 'oneOf')) expect(strict(args)).toBe(false);
223 + }
224 + }
225 +
226 + const again = toStrictJsonSchema(result.schema);
227 + expect(again.schema).toEqual(result.schema);
228 + expect(again.changes).toEqual([]);
229 + }),
230 + { numRuns: RUNS }
231 + );
232 + });
233 +
234 + it('null is kept exactly when the tool schema accepts it', { timeout: TIMEOUT_MS }, () => {
235 + fc.assert(
236 + fc.property(propertySchema(ALL_COMPOSITIONS), property => {
237 + const source = toolSchema(property);
238 + const accepted = validatorFor(source)({ value: null });
239 + expect(omitNullToolArguments({ value: null }, source)).toEqual(
240 + accepted ? { value: null } : {}
241 + );
242 + }),
243 + { numRuns: RUNS }
244 + );
245 + });
246 +});
ts/packages/core/test/utils/jsonSchema.strict.test.ts
+266
@@ -470,3 +470,269 @@ describe('omitNullToolArguments', () => {
470 expect(input).toEqual(snapshot);
471 });
472 });
473 +
474 +describe('null acceptance', () => {
475 + const NULL_BRANCH = { type: 'null' };
476 + const DIRECTION = { enum: ['asc', null] };
477 + const wrapped = (schema: unknown) => ({ anyOf: [schema, NULL_BRANCH] });
478 + const toolSchema = (property: unknown, definitions: unknown = { Direction: DIRECTION }) => ({
479 + type: 'object',
480 + properties: { value: property },
481 + $defs: definitions,
482 + });
483 +
484 + it.each<[Record<string, unknown>, Record<string, unknown>]>([
485 + [{ type: 'string', enum: ['asc', 'desc'] }, wrapped({ type: 'string', enum: ['asc', 'desc'] })],
486 + [
487 + { type: ['string', 'null'], enum: ['asc', 'desc'] },
488 + wrapped({ type: ['string', 'null'], enum: ['asc', 'desc'] }),
489 + ],
490 + [{ type: 'string', const: 'asc' }, wrapped({ type: 'string', const: 'asc' })],
491 + [
492 + { type: 'integer', enum: [1, 2], description: 'page size' },
493 + { description: 'page size', ...wrapped({ type: 'integer', enum: [1, 2] }) },
494 + ],
495 + [
496 + { type: 'string', anyOf: [{ minLength: 1 }] },
497 + wrapped({ type: 'string', anyOf: [{ minLength: 1 }] }),
498 + ],
499 + [
500 + { enum: ['asc'], anyOf: [{ type: 'string' }, NULL_BRANCH] },
501 + wrapped({ enum: ['asc'], anyOf: [{ type: 'string' }, NULL_BRANCH] }),
502 + ],
503 + [
504 + { $ref: '#/$defs/Direction', type: 'string' },
505 + wrapped({ $ref: '#/$defs/Direction', type: 'string' }),
506 + ],
507 + // Already nullable: left alone.
508 + [
509 + { type: ['string', 'null'], enum: ['asc', null] },
510 + { type: ['string', 'null'], enum: ['asc', null] },
511 + ],
512 + [{ $ref: '#/$defs/Direction' }, { $ref: '#/$defs/Direction' }],
513 + [{ anyOf: [{ type: ['string', 'null'] }] }, { anyOf: [{ type: ['string', 'null'] }] }],
514 + // `type` or `anyOf` as the only obstacle: widened in place.
515 + [
516 + { type: 'string', minLength: 1 },
517 + { type: ['string', 'null'], minLength: 1 },
518 + ],
519 + [
520 + { anyOf: [{ type: 'string' }], description: 'd' },
521 + { anyOf: [{ type: 'string' }, NULL_BRANCH], description: 'd' },
522 + ],
523 + ])('widening keeps every constraint: %j', (property, expected) => {
524 + const source = toolSchema(property);
525 + const snapshot = structuredClone(source);
526 + const result = toStrictJsonSchema(source);
527 +
528 + expect(result.unsupported).toEqual([]);
529 + expect(propertyOf(result.schema, 'value')).toEqual(expected);
530 + expect(result.schema.required).toEqual(['value']);
531 + expect(source).toEqual(snapshot);
532 + const again = toStrictJsonSchema(result.schema);
533 + expect(again.schema).toEqual(result.schema);
534 + expect(again.changes).toEqual([]);
535 + });
536 +
537 + it.each<[unknown, boolean]>([
538 + [{ type: ['string', 'null'], enum: ['asc', 'desc'] }, false],
539 + [{ type: ['string', 'null'], const: 'asc' }, false],
540 + [{ type: ['string', 'null'], enum: ['asc', null] }, true],
541 + [{ type: ['string', 'null'], const: null }, true],
542 + [{ $ref: '#/$defs/Direction' }, true],
543 + [{ $ref: '#/$defs/Direction', type: 'string' }, false],
544 + [{ $ref: '#/$defs/Direction', enum: ['asc'] }, false],
545 + [{ $ref: '#/$defs/Missing' }, false],
546 + [{ $ref: 1 }, false],
547 + [{ allOf: [{ type: ['string', 'null'] }, { enum: ['asc'] }] }, false],
548 + [{ allOf: [{ type: ['string', 'null'] }, DIRECTION] }, true],
549 + [{ oneOf: [NULL_BRANCH, { type: 'string' }] }, true],
550 + [{ oneOf: [NULL_BRANCH, { enum: [null] }] }, false],
551 + [{ not: NULL_BRANCH }, false],
552 + [{ not: { type: 'string' } }, true],
553 + [{ if: NULL_BRANCH, then: { type: 'string' } }, false],
554 + [{ if: { type: 'string' }, then: { type: 'string' } }, true],
555 + [{ if: { type: 'string' }, else: { type: 'string' } }, false],
556 + [true, true],
557 + [false, false],
558 + ])('null is kept only when every keyword accepts it: %j', (property, kept) => {
559 + const input = { value: null };
560 + expect(omitNullToolArguments(input, toolSchema(property))).toEqual(kept ? { value: null } : {});
561 + expect(input).toEqual({ value: null });
562 + });
563 +
564 + it.each<[Record<string, unknown>, boolean]>([
565 + [{ a: { $ref: '#/$defs/a' } }, false],
566 + [{ a: { $ref: '#/$defs/b' }, b: { $ref: '#/$defs/a' } }, false],
567 + [{ a: { anyOf: [{ $ref: '#/$defs/a' }] } }, false],
568 + [{ a: { type: 'null', oneOf: [{ $ref: '#/$defs/a' }] } }, false],
569 + [{ a: { anyOf: [{ $ref: '#/$defs/b' }] }, b: { anyOf: [{ $ref: '#/$defs/a' }] } }, false],
570 + [{ a: { anyOf: [{ $ref: '#/$defs/a' }, NULL_BRANCH] } }, true],
571 + [{ a: { oneOf: [{ $ref: '#/$defs/a' }, NULL_BRANCH] } }, true],
572 + ])('reference cycles terminate: %j', (definitions, kept) => {
573 + const source = toolSchema({ $ref: '#/$defs/a' }, definitions);
574 + expect(omitNullToolArguments({ value: null }, source)).toEqual(kept ? { value: null } : {});
575 + expect(toStrictJsonSchema(source).unsupported).toEqual([]);
576 + });
577 +
578 + it('checks a node reached twice outside a cycle each time', () => {
579 + const shared = { anyOf: [NULL_BRANCH] };
580 + const source = { type: 'object', properties: { value: { allOf: [shared, shared] } } };
581 + expect(omitNullToolArguments({ value: null }, source)).toEqual({ value: null });
582 + });
583 +
584 + /** `a0` is the leaf; every `a(i)` references `a(i-1)` twice, so paths double per level. */
585 + const diamond = (levels: number, keyword: string, leaf: unknown) => {
586 + const definitions: Record<string, unknown> = { a0: leaf };
587 + for (let i = 1; i <= levels; i++) {
588 + const ref = { $ref: `#/$defs/a${i - 1}` };
589 + definitions[`a${i}`] = { [keyword]: [ref, ref] };
590 + }
591 + return toolSchema({ $ref: `#/$defs/a${levels}` }, definitions);
592 + };
593 +
594 + it('evaluates a definition shared by many branches once', () => {
595 + const rejecting = diamond(20, 'anyOf', { type: 'string' });
596 + expect(propertyOf(toStrictJsonSchema(rejecting).schema, 'value')).toEqual(
597 + wrapped({ $ref: '#/$defs/a20' })
598 + );
599 + expect(omitNullToolArguments({ value: null }, rejecting)).toEqual({});
600 +
601 + const accepting = diamond(20, 'allOf', NULL_BRANCH);
602 + expect(omitNullToolArguments({ value: null }, accepting)).toEqual({ value: null });
603 + });
604 +
605 + it('stays bounded when cycles keep answers from being remembered', () => {
606 + // Every level also points back at the top, so no answer below it is final.
607 + const levels = 20;
608 + const definitions: Record<string, unknown> = { a0: { type: 'string' } };
609 + for (let i = 1; i <= levels; i++) {
610 + const ref = { $ref: `#/$defs/a${i - 1}` };
611 + definitions[`a${i}`] = { anyOf: [ref, ref, { $ref: `#/$defs/a${levels}` }] };
612 + }
613 + const source = toolSchema({ $ref: `#/$defs/a${levels}` }, definitions);
614 + expect(omitNullToolArguments({ value: null }, source)).toEqual({});
615 + expect(propertyOf(toStrictJsonSchema(source).schema, 'value')).toEqual(
616 + wrapped({ $ref: `#/$defs/a${levels}` })
617 + );
618 + });
619 +
620 + it('does not prove null through a reference chain past the depth bound', () => {
621 + const definitions: Record<string, unknown> = { a0: NULL_BRANCH };
622 + for (let i = 1; i <= 100; i++) definitions[`a${i}`] = { $ref: `#/$defs/a${i - 1}` };
623 + expect(
624 + omitNullToolArguments({ value: null }, toolSchema({ $ref: '#/$defs/a100' }, definitions))
625 + ).toEqual({});
626 + expect(
627 + omitNullToolArguments({ value: null }, toolSchema({ $ref: '#/$defs/a10' }, definitions))
628 + ).toEqual({ value: null });
629 + });
630 +
631 + it('adds a null branch to a $ref whose target the rewrite types as an object', () => {
632 + const source = {
633 + type: 'object',
634 + properties: { node: { $ref: '#/$defs/Node' } },
635 + $defs: {
636 + Node: { properties: { label: { type: 'string' }, child: { $ref: '#/$defs/Node' } } },
637 + },
638 + };
639 + const { schema, unsupported } = toStrictJsonSchema(source);
640 + const definitions = schema.$defs as Record<string, Record<string, unknown>>;
641 +
642 + expect(unsupported).toEqual([]);
643 + expect(propertyOf(schema, 'node')).toEqual(wrapped({ $ref: '#/$defs/Node' }));
644 + expect(definitions.Node.type).toBe('object');
645 + expect(propertyOf(definitions.Node, 'child')).toEqual(wrapped({ $ref: '#/$defs/Node' }));
646 + // The tool's own schema accepts the null, so it is forwarded.
647 + expect(omitNullToolArguments({ node: null }, source)).toEqual({ node: null });
648 + });
649 +
650 + it('reports a $ref into a property that wrapping moved', () => {
651 + const { unsupported } = toStrictJsonSchema({
652 + type: 'object',
653 + properties: {
654 + value: { type: 'string', enum: ['asc'], $defs: { Text: { type: 'string' } } },
655 + alias: { $ref: '#/properties/value/$defs/Text' },
656 + },
657 + required: ['alias'],
658 + });
659 + expect(unsupported.map(({ path, keyword }) => ({ path, keyword }))).toEqual([
660 + { path: 'properties.alias', keyword: '$ref' },
661 + ]);
662 + });
663 +
664 + it('shares what it learned about a cyclic definition across many properties', () => {
665 + const levels = 20;
666 + const top = `#/$defs/a${levels}`;
667 + const definitions: Record<string, unknown> = { a0: { type: 'string' } };
668 + for (let i = 1; i <= levels; i++) {
669 + const lower = `#/$defs/a${i - 1}`;
670 + definitions[`a${i}`] = { anyOf: [{ $ref: lower }, { $ref: lower }, { $ref: top }] };
671 + }
672 + const names = Array.from({ length: 400 }, (_, i) => `p${i}`);
673 + const source = {
674 + type: 'object',
675 + properties: Object.fromEntries(names.map(name => [name, { $ref: top }])),
676 + $defs: definitions,
677 + };
678 + const { schema } = toStrictJsonSchema(source);
679 + for (const name of names) expect(propertyOf(schema, name)).toEqual(wrapped({ $ref: top }));
680 + const input = Object.fromEntries(names.map(name => [name, null]));
681 + expect(omitNullToolArguments(input, source)).toEqual({});
682 + });
683 +
684 + it('keeps a check that runs out of budget from affecting the next one', () => {
685 + const source = {
686 + type: 'object',
687 + properties: {
688 + wide: { anyOf: Array.from({ length: 5000 }, () => ({ type: 'string' })) },
689 + note: { type: ['string', 'null'] },
690 + same: { anyOf: [{ type: 'string' }, NULL_BRANCH] },
691 + },
692 + };
693 + expect(omitNullToolArguments({ wide: null, note: null, same: null }, source)).toEqual({
694 + note: null,
695 + same: null,
696 + });
697 + const { schema } = toStrictJsonSchema(source);
698 + expect(propertyOf(schema, 'note')).toEqual({ type: ['string', 'null'] });
699 + expect(propertyOf(schema, 'same')).toEqual({ anyOf: [{ type: 'string' }, NULL_BRANCH] });
700 + });
701 +
702 + it('proves nothing in a check that meets a bound', () => {
703 + // Both branches accept null, so `oneOf` rejects it; the second is only
704 + // reachable past the depth bound and must not count as a rejection.
705 + const definitions: Record<string, unknown> = { a0: NULL_BRANCH };
706 + for (let i = 1; i <= 70; i++) definitions[`a${i}`] = { $ref: `#/$defs/a${i - 1}` };
707 + const deep = { $ref: '#/$defs/a70' };
708 + const properties = {
709 + one: { oneOf: [NULL_BRANCH, deep] },
710 + negated: { not: deep },
711 + guarded: { if: deep, else: NULL_BRANCH },
712 + // Reaches a node the checks above left unproven.
713 + later: { not: { $ref: '#/$defs/a69' } },
714 + };
715 + const source = { type: 'object', properties, $defs: definitions };
716 + const input = Object.fromEntries(Object.keys(properties).map(name => [name, null]));
717 + expect(omitNullToolArguments(input, source)).toEqual({});
718 + });
719 +
720 + it('does not evaluate an unproven definition again for each property', () => {
721 + // `top` is cyclic and wider than the budget, so nothing about it settles.
722 + const top = { $ref: '#/$defs/top' };
723 + const definitions: Record<string, unknown> = {
724 + top: { anyOf: Array.from({ length: 3000 }, (_, i) => ({ $ref: `#/$defs/b${i}` })) },
725 + };
726 + for (let i = 0; i < 3000; i++) definitions[`b${i}`] = { anyOf: [top, { type: 'string' }] };
727 + const names = Array.from({ length: 2000 }, (_, i) => `p${i}`);
728 + const source = {
729 + type: 'object',
730 + properties: Object.fromEntries(names.map(name => [name, { ...top }])),
731 + $defs: definitions,
732 + };
733 + const input = Object.fromEntries(names.map(name => [name, null]));
734 + expect(omitNullToolArguments(input, source)).toEqual({});
735 + const { schema } = toStrictJsonSchema(source);
736 + for (const name of names) expect(propertyOf(schema, name)).toEqual(wrapped(top));
737 + });
738 +});