1
+"""Tests for :func:`composio.utils.json_schema.dereference_json_schema`.
2
+
3
+Mirrors the TypeScript SDK's ``jsonSchema.test.ts`` so the two SDKs share one
4
+behavioral contract for inlining JSON Schema ``$ref`` pointers.
5
+"""
6
+
7
+import typing as t
8
+from unittest.mock import patch
9
+
10
+import pytest
11
+
12
+from composio.exceptions import JSONSchemaRefResolutionError
13
+from composio.utils import json_schema
14
+from composio.utils.json_schema import (
15
+ MAX_REF_CHAIN_DEPTH,
16
+ UNRESOLVED_REF_DESCRIPTION,
17
+ dereference_json_schema,
18
+)
19
+
20
+
21
+def _contains_ref(value: t.Any) -> bool:
22
+ if isinstance(value, dict):
23
+ if "$ref" in value:
24
+ return True
25
+ return any(_contains_ref(v) for v in value.values())
26
+ if isinstance(value, list):
27
+ return any(_contains_ref(v) for v in value)
28
+ return False
29
+
30
+
31
+PERMISSIVE: t.Dict[str, t.Any] = {"type": "object", "additionalProperties": True}
32
+PERMISSIVE_WITH_HINT: t.Dict[str, t.Any] = {
33
+ **PERMISSIVE,
34
+ "description": UNRESOLVED_REF_DESCRIPTION,
35
+}
36
+
37
+
38
+class TestDereferenceJsonSchema:
39
+ def test_inlines_single_internal_ref(self):
40
+ out = dereference_json_schema(
41
+ {
42
+ "type": "object",
43
+ "properties": {"user": {"$ref": "#/$defs/User"}},
44
+ "required": ["user"],
45
+ "$defs": {"User": {"type": "string"}},
46
+ }
47
+ )
48
+ assert out == {
49
+ "type": "object",
50
+ "properties": {"user": {"type": "string"}},
51
+ "required": ["user"],
52
+ }
53
+ assert _contains_ref(out) is False
54
+
55
+ def test_resolves_chain_a_b_c(self):
56
+ out = dereference_json_schema(
57
+ {
58
+ "type": "object",
59
+ "properties": {"v": {"$ref": "#/$defs/A"}},
60
+ "$defs": {
61
+ "A": {"$ref": "#/$defs/B"},
62
+ "B": {"$ref": "#/$defs/C"},
63
+ "C": {"type": "integer"},
64
+ },
65
+ }
66
+ )
67
+ assert _contains_ref(out) is False
68
+ assert out["properties"]["v"] == {"type": "integer"}
69
+
70
+ def test_walks_containers_reflectively(self):
71
+ """Refs are resolved in keywords the file walkers never special-cased."""
72
+ out = dereference_json_schema(
73
+ {
74
+ "type": "object",
75
+ "properties": {
76
+ "a": {"type": "array", "items": {"$ref": "#/$defs/Leaf"}},
77
+ "b": {"oneOf": [{"$ref": "#/$defs/Leaf"}, {"type": "null"}]},
78
+ "c": {"anyOf": [{"$ref": "#/$defs/Leaf"}]},
79
+ "d": {"allOf": [{"$ref": "#/$defs/Leaf"}]},
80
+ "e": {"not": {"$ref": "#/$defs/Leaf"}},
81
+ "f": {
82
+ "type": "object",
83
+ "additionalProperties": {"$ref": "#/$defs/Leaf"},
84
+ },
85
+ "g": {
86
+ "type": "object",
87
+ "patternProperties": {"^x_": {"$ref": "#/$defs/Leaf"}},
88
+ },
89
+ "h": {"type": "array", "prefixItems": [{"$ref": "#/$defs/Leaf"}]},
90
+ },
91
+ "$defs": {"Leaf": {"type": "string"}},
92
+ }
93
+ )
94
+ assert _contains_ref(out) is False
95
+
96
+ def test_resolves_legacy_definitions(self):
97
+ out = dereference_json_schema(
98
+ {
99
+ "type": "object",
100
+ "properties": {"name": {"$ref": "#/definitions/Name"}},
101
+ "definitions": {"Name": {"type": "string", "minLength": 1}},
102
+ }
103
+ )
104
+ assert _contains_ref(out) is False
105
+ assert out["properties"]["name"] == {"type": "string", "minLength": 1}
106
+
107
+ def test_mixes_defs_and_definitions_transitively(self):
108
+ out = dereference_json_schema(
109
+ {
110
+ "type": "object",
111
+ "properties": {"v": {"$ref": "#/definitions/A"}},
112
+ "definitions": {"A": {"$ref": "#/$defs/B"}},
113
+ "$defs": {"B": {"type": "boolean"}},
114
+ }
115
+ )
116
+ assert _contains_ref(out) is False
117
+ assert out["properties"]["v"] == {"type": "boolean"}
118
+
119
+ def test_sibling_keywords_win_on_collision(self):
120
+ out = dereference_json_schema(
121
+ {
122
+ "type": "object",
123
+ "properties": {
124
+ "v": {
125
+ "$ref": "#/$defs/Foo",
126
+ "description": "caller override",
127
+ "default": None,
128
+ },
129
+ },
130
+ "$defs": {
131
+ "Foo": {"type": "string", "description": "target description"}
132
+ },
133
+ }
134
+ )
135
+ v = out["properties"]["v"]
136
+ assert v["type"] == "string"
137
+ assert v["description"] == "caller override"
138
+ assert v["default"] is None
139
+ assert _contains_ref(out) is False
140
+
141
+ def test_breaks_recursive_ref_cycles_with_sentinel(self):
142
+ out = dereference_json_schema(
143
+ {
144
+ "$ref": "#/$defs/Tree",
145
+ "$defs": {
146
+ "Tree": {
147
+ "type": "object",
148
+ "properties": {
149
+ "children": {
150
+ "type": "array",
151
+ "items": {"$ref": "#/$defs/Tree"},
152
+ },
153
+ },
154
+ },
155
+ },
156
+ }
157
+ )
158
+ assert out["type"] == "object"
159
+ assert out["properties"]["children"]["items"] == PERMISSIVE
160
+ assert _contains_ref(out) is False
161
+
162
+ def test_strips_defs_and_definitions_from_root(self):
163
+ out = dereference_json_schema(
164
+ {
165
+ "type": "object",
166
+ "properties": {"x": {"$ref": "#/$defs/Foo"}},
167
+ "$defs": {"Foo": {"type": "integer"}},
168
+ "definitions": {"Bar": {"type": "string"}},
169
+ }
170
+ )
171
+ assert "$defs" not in out
172
+ assert "definitions" not in out
173
+
174
+ def test_throws_when_target_missing(self):
175
+ with pytest.raises(JSONSchemaRefResolutionError):
176
+ dereference_json_schema(
177
+ {
178
+ "type": "object",
179
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
180
+ "$defs": {},
181
+ }
182
+ )
183
+
184
+ def test_throws_when_chain_depth_exceeds_cap(self):
185
+ defs: t.Dict[str, t.Any] = {}
186
+ for i in range(200):
187
+ target = f"#/$defs/A{i + 1}" if i + 1 < 200 else "#/$defs/A0"
188
+ defs[f"A{i}"] = {"$ref": target}
189
+ with pytest.raises(JSONSchemaRefResolutionError):
190
+ dereference_json_schema(
191
+ {
192
+ "type": "object",
193
+ "properties": {"v": {"$ref": "#/$defs/A0"}},
194
+ "$defs": defs,
195
+ }
196
+ )
197
+
198
+ def test_throws_on_pathologically_deep_nesting(self):
199
+ leaf: t.Dict[str, t.Any] = {"type": "string"}
200
+ for _ in range(1000):
201
+ leaf = {"type": "object", "properties": {"x": leaf}}
202
+ with pytest.raises(JSONSchemaRefResolutionError):
203
+ dereference_json_schema(leaf)
204
+
205
+ def test_breaks_identity_cycles_without_ref(self):
206
+ """A live-object cycle that does not flow through a ``$ref``."""
207
+ root: t.Dict[str, t.Any] = {"type": "object", "properties": {}}
208
+ root["properties"]["self"] = root
209
+ out = dereference_json_schema(root)
210
+ assert out["properties"]["self"] == PERMISSIVE
211
+
212
+ def test_leaves_external_ref_untouched_and_warns(self):
213
+ with patch.object(json_schema.logger, "warning") as warn:
214
+ out = dereference_json_schema(
215
+ {
216
+ "type": "object",
217
+ "properties": {"v": {"$ref": "https://example.com/Foo"}},
218
+ }
219
+ )
220
+ assert out["properties"]["v"]["$ref"] == "https://example.com/Foo"
221
+ warn.assert_called_once()
222
+ assert "https://example.com/Foo" in str(warn.call_args)
223
+
224
+ def test_does_not_mutate_input(self):
225
+ import copy
226
+
227
+ schema = {
228
+ "type": "object",
229
+ "properties": {"v": {"$ref": "#/$defs/Foo"}},
230
+ "$defs": {"Foo": {"type": "string"}},
231
+ }
232
+ snapshot = copy.deepcopy(schema)
233
+ dereference_json_schema(schema)
234
+ assert schema == snapshot
235
+
236
+ def test_decodes_json_pointer_escapes(self):
237
+ out = dereference_json_schema(
238
+ {
239
+ "type": "object",
240
+ "properties": {
241
+ "a": {"$ref": "#/$defs/with~1slash"},
242
+ "b": {"$ref": "#/$defs/with~0tilde"},
243
+ "c": {"$ref": "#/$defs/tilde-then-slash~01"},
244
+ },
245
+ "$defs": {
246
+ "with/slash": {"type": "string"},
247
+ "with~tilde": {"type": "integer"},
248
+ "tilde-then-slash~1": {"type": "boolean"},
249
+ },
250
+ }
251
+ )
252
+ props = out["properties"]
253
+ assert props["a"]["type"] == "string"
254
+ assert props["b"]["type"] == "integer"
255
+ assert props["c"]["type"] == "boolean"
256
+
257
+ def test_resolves_array_index_pointers(self):
258
+ out = dereference_json_schema(
259
+ {
260
+ "type": "object",
261
+ "properties": {"v": {"$ref": "#/$defs/foo/oneOf/0"}},
262
+ "$defs": {"foo": {"oneOf": [{"type": "string"}, {"type": "number"}]}},
263
+ }
264
+ )
265
+ assert out["properties"]["v"]["type"] == "string"
266
+
267
+ def test_passthrough_for_non_dict_input(self):
268
+ assert dereference_json_schema("not-a-schema") == "not-a-schema"
269
+ assert dereference_json_schema(None) is None
270
+
271
+
272
+class TestSentinelMode:
273
+ def test_replaces_dangling_ref_with_no_defs_block(self):
274
+ """Mirrors GMAIL_FETCH_EMAILS: a ``$ref`` into ``#/$defs`` with no defs."""
275
+ out = dereference_json_schema(
276
+ {
277
+ "type": "object",
278
+ "properties": {
279
+ "data": {"$ref": "#/$defs/FetchEmailsResponse"},
280
+ "error": {"type": "string"},
281
+ "successful": {"type": "boolean"},
282
+ },
283
+ "required": ["data", "successful"],
284
+ "title": "FetchEmailsResponseWrapper",
285
+ },
286
+ on_unresolved="sentinel",
287
+ )
288
+ assert out["properties"]["data"] == PERMISSIVE_WITH_HINT
289
+ assert out["properties"]["error"] == {"type": "string"}
290
+ assert out["properties"]["successful"] == {"type": "boolean"}
291
+ assert out["required"] == ["data", "successful"]
292
+ assert _contains_ref(out) is False
293
+
294
+ def test_replaces_ref_into_empty_defs(self):
295
+ out = dereference_json_schema(
296
+ {
297
+ "type": "object",
298
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
299
+ "$defs": {},
300
+ },
301
+ on_unresolved="sentinel",
302
+ )
303
+ assert out["properties"]["v"] == PERMISSIVE_WITH_HINT
304
+ assert _contains_ref(out) is False
305
+
306
+ def test_on_replace_called_once_per_replacement(self):
307
+ calls: t.List[t.Tuple[str, str]] = []
308
+ dereference_json_schema(
309
+ {
310
+ "type": "object",
311
+ "properties": {
312
+ "a": {"$ref": "#/$defs/Missing"},
313
+ "b": {"$ref": "#/$defs/Missing"},
314
+ "c": {"$ref": "#/$defs/AlsoMissing"},
315
+ },
316
+ },
317
+ on_unresolved="sentinel",
318
+ on_replace=lambda ref, reason: calls.append((ref, reason)),
319
+ )
320
+ assert calls == [
321
+ ("#/$defs/Missing", "missing-target"),
322
+ ("#/$defs/Missing", "missing-target"),
323
+ ("#/$defs/AlsoMissing", "missing-target"),
324
+ ]
325
+
326
+ def test_on_replace_malformed_pointer(self):
327
+ calls: t.List[t.Tuple[str, str]] = []
328
+ out = dereference_json_schema(
329
+ {"type": "object", "properties": {"v": {"$ref": "#bar"}}},
330
+ on_unresolved="sentinel",
331
+ on_replace=lambda ref, reason: calls.append((ref, reason)),
332
+ )
333
+ assert calls == [("#bar", "malformed-pointer")]
334
+ assert out["properties"]["v"] == PERMISSIVE_WITH_HINT
335
+
336
+ def test_still_throws_on_chain_depth_cap(self):
337
+ defs: t.Dict[str, t.Any] = {}
338
+ for i in range(200):
339
+ target = f"#/$defs/A{i + 1}" if i + 1 < 200 else "#/$defs/A0"
340
+ defs[f"A{i}"] = {"$ref": target}
341
+ with pytest.raises(JSONSchemaRefResolutionError):
342
+ dereference_json_schema(
343
+ {
344
+ "type": "object",
345
+ "properties": {"v": {"$ref": "#/$defs/A0"}},
346
+ "$defs": defs,
347
+ },
348
+ on_unresolved="sentinel",
349
+ )
350
+
351
+ def test_still_throws_on_node_depth_cap(self):
352
+ leaf: t.Dict[str, t.Any] = {"type": "string"}
353
+ for _ in range(1000):
354
+ leaf = {"type": "object", "properties": {"x": leaf}}
355
+ with pytest.raises(JSONSchemaRefResolutionError):
356
+ dereference_json_schema(leaf, on_unresolved="sentinel")
357
+
358
+ def test_explicit_throw_matches_default(self):
359
+ with pytest.raises(JSONSchemaRefResolutionError):
360
+ dereference_json_schema(
361
+ {
362
+ "type": "object",
363
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
364
+ "$defs": {},
365
+ },
366
+ on_unresolved="throw",
367
+ )
368
+
369
+ def test_does_not_call_on_replace_in_strict_mode(self):
370
+ calls: t.List[t.Any] = []
371
+ with pytest.raises(JSONSchemaRefResolutionError):
372
+ dereference_json_schema(
373
+ {
374
+ "type": "object",
375
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
376
+ "$defs": {},
377
+ },
378
+ on_unresolved="throw",
379
+ on_replace=lambda ref, reason: calls.append((ref, reason)),
380
+ )
381
+ assert calls == []
382
+
383
+ def test_injects_default_description_when_no_sibling(self):
384
+ out = dereference_json_schema(
385
+ {"type": "object", "properties": {"v": {"$ref": "#/$defs/Missing"}}},
386
+ on_unresolved="sentinel",
387
+ )
388
+ description = out["properties"]["v"]["description"]
389
+ assert "Schema shape unresolved at the source" in description
390
+ assert "https://github.com/ComposioHQ/composio/issues/3307" in description
391
+
392
+ def test_preserves_caller_description_sibling(self):
393
+ out = dereference_json_schema(
394
+ {
395
+ "type": "object",
396
+ "properties": {
397
+ "v": {
398
+ "$ref": "#/$defs/Missing",
399
+ "description": "caller-supplied prose context",
400
+ },
401
+ },
402
+ },
403
+ on_unresolved="sentinel",
404
+ )
405
+ assert out["properties"]["v"]["description"] == "caller-supplied prose context"
406
+ assert out["properties"]["v"]["type"] == "object"
407
+
408
+ def test_preserves_resolvable_defs_while_replacing_dangling_branch(self):
409
+ out = dereference_json_schema(
410
+ {
411
+ "type": "object",
412
+ "properties": {
413
+ "resolved": {"$ref": "#/$defs/Real"},
414
+ "dangling": {"$ref": "#/$defs/Ghost"},
415
+ },
416
+ "$defs": {"Real": {"type": "integer"}},
417
+ },
418
+ on_unresolved="sentinel",
419
+ )
420
+ assert out["properties"]["resolved"] == {"type": "integer"}
421
+ assert out["properties"]["dangling"] == PERMISSIVE_WITH_HINT
422
+
423
+
424
+def test_max_ref_chain_depth_is_exposed():
425
+ """Guard against accidental removal of the safety cap constant."""
426
+ assert MAX_REF_CHAIN_DEPTH == 100