Skip to content

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

fix(py): resolve $ref/$defs so file flags behind a reference aren't dropped (#3653)

Alberto Schiabelaeeb471c6341
diff --git a/python/composio/core/models/_files.py b/python/composio/core/models/_files.py
index 57f1d0ae7..35985c5a8 100644
--- a/python/composio/core/models/_files.py
+++ b/python/composio/core/models/_files.py
@@ -24,6 +24,7 @@ from composio.exceptions import (
SDKFileNotFoundError,
)
from composio.utils import mimetypes
+from composio.utils.json_schema import dereference_json_schema
from composio.utils.sensitive_file_upload_paths import (
assert_safe_local_file_upload_path,
)
@@ -813,10 +814,23 @@ class FileHelper(WithLogger):
Should only be called when the caller opted in via
`dangerously_allow_auto_upload_download_files=True`.
Recursively handles anyOf, oneOf, allOf, nested properties, and array items.
+
+ ``$ref``/``$defs`` indirection is inlined first so file_uploadable flags
+ reachable only through a reference are visible to the transform below
+ (https://github.com/ComposioHQ/composio/issues/3506). Tool schemas come
+ from the API, which may emit a ``$ref`` without a ``$defs`` block
+ (https://github.com/ComposioHQ/composio/issues/3307); ``"sentinel"``
+ degrades that gracefully instead of raising.
"""
- if "properties" not in schema:
+ resolved = dereference_json_schema(schema, on_unresolved="sentinel")
+ if "properties" not in resolved:
return schema
+ # Preserve the original object's identity (callers such as
+ # ``process_schema_recursively`` mutate in place) while adopting the
+ # dereferenced, ``$defs``-stripped shape.
+ schema.clear()
+ schema.update(resolved)
schema["properties"] = {
key: self._transform_schema_for_file_upload(prop)
for key, prop in schema["properties"].items()
@@ -1042,7 +1056,12 @@ class FileHelper(WithLogger):
"""
return self._substitute_file_uploads_recursively(
tool=tool,
- schema=tool.input_parameters,
+ # Inline $ref/$defs once at the boundary so the walker sees
+ # file_uploadable flags hidden behind a reference. Non-mutating:
+ # ``tool.input_parameters`` is left untouched.
+ schema=dereference_json_schema(
+ tool.input_parameters, on_unresolved="sentinel"
+ ),
request=request,
before_file_upload=before_file_upload,
)
@@ -1160,7 +1179,13 @@ class FileHelper(WithLogger):
"ToolExecutionResponse",
self._substitute_file_downloads_recursively(
tool=tool,
- schema=tool.output_parameters,
+ # Inline $ref/$defs once at the boundary so the walker sees
+ # file_downloadable flags hidden behind a reference (e.g.
+ # GMAIL_GET_ATTACHMENT). Non-mutating: ``tool.output_parameters``
+ # is left untouched.
+ schema=dereference_json_schema(
+ tool.output_parameters, on_unresolved="sentinel"
+ ),
request=t.cast(dict, response),
),
)
diff --git a/python/composio/exceptions.py b/python/composio/exceptions.py
index c8c124834..91bdf8d61 100644
--- a/python/composio/exceptions.py
+++ b/python/composio/exceptions.py
@@ -79,6 +79,25 @@ class ValidationError(ComposioError):
pass
+class JSONSchemaRefResolutionError(ValidationError):
+ """Raised when an internal JSON Schema ``$ref`` cannot be inlined.
+
+ Covers malformed pointers, missing ``$defs``/``definitions`` targets
+ (strict mode only), and ``$ref`` chains or node nesting that exceed the
+ safety caps in :func:`composio.utils.json_schema.dereference_json_schema`.
+ """
+
+ def __init__(
+ self,
+ message: str,
+ *args: t.Any,
+ meta: t.Optional[t.Dict[str, t.Any]] = None,
+ delegate: bool = False,
+ ) -> None:
+ super().__init__(message, *args, delegate=delegate)
+ self.meta = meta or {}
+
+
class ToolkitError(ComposioError):
pass
diff --git a/python/composio/utils/json_schema.py b/python/composio/utils/json_schema.py
new file mode 100644
index 000000000..0dc4ab559
--- /dev/null
+++ b/python/composio/utils/json_schema.py
@@ -0,0 +1,257 @@
+"""Inline internal JSON Schema ``$ref`` pointers.
+
+Python counterpart of the TypeScript SDK's ``dereferenceJsonSchema``
+(``ts/packages/core/src/utils/jsonSchema.ts``). Hand-rolled schema walkers in
+the SDK (e.g. the file-upload/download substitution in
+:mod:`composio.core.models._files`) recurse through ``properties``/``anyOf``/
+``oneOf``/``allOf``/``items`` but do not dereference ``$ref``. The Composio API
+emits tool parameter schemas with ``$ref``/``$defs`` indirection (``GMAIL_GET_
+ATTACHMENT`` is the canonical shape), so a ``file_uploadable``/``file_
+downloadable`` flag reachable only through a reference is silently missed.
+
+Resolving references *once* at the boundary — rather than teaching every walker
+to dereference — keeps the walkers reference-agnostic and gives all of them
+``$ref`` support for free, including keywords they never special-cased
+(``additionalProperties``, ``patternProperties``, ``prefixItems``, ``not``, …),
+because :func:`dereference_json_schema` walks containers reflectively.
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+from composio.exceptions import JSONSchemaRefResolutionError
+from composio.utils.logging import get as get_logger
+
+logger = get_logger()
+
+# A ``$ref`` chain longer than this, or object nesting deeper than this, is
+# treated as pathological (cyclic data, a billion-laughs-style schema) and
+# raises rather than exhausting the interpreter's recursion limit. The caps
+# fire in both strict and lenient modes — leniency applies to *unresolvable*
+# refs, not to runaway expansion.
+MAX_REF_CHAIN_DEPTH = 100
+MAX_NODE_DEPTH = 512
+
+# In-band hint attached to the sentinel when lenient mode stands in for an
+# unresolvable ``$ref``. Makes the degradation visible to an LLM reading the
+# schema instead of leaving it a bare permissive object. Overridden by a
+# caller-provided ``description`` sibling (Draft 2020-12 sibling-keyword merge).
+UNRESOLVED_REF_DESCRIPTION = (
+ "Schema shape unresolved at the source — validate loosely. "
+ "See https://github.com/ComposioHQ/composio/issues/3307."
+)
+
+# Strategy when an internal ``$ref`` cannot be resolved.
+# - ``"throw"`` (default): raise ``JSONSchemaRefResolutionError``. Right for
+# first-party / custom-tool schemas where a dangling ``$ref`` is a bug.
+# - ``"sentinel"``: replace the node with a permissive object. Right for
+# schemas from an upstream service the caller cannot edit (the Composio API
+# ships some ``output_parameters`` with a ``$ref`` into ``#/$defs/...`` but no
+# ``$defs`` block — see https://github.com/ComposioHQ/composio/issues/3307).
+UnresolvedRefStrategy = t.Literal["throw", "sentinel"]
+UnresolvedRefReason = t.Literal["missing-target", "malformed-pointer"]
+
+# Callback invoked once per replaced node in ``"sentinel"`` mode.
+OnReplace = t.Callable[[str, "UnresolvedRefReason"], None]
+
+
+def _cycle_break_sentinel() -> t.Dict[str, t.Any]:
+ """A fresh permissive object used to break cycles / stand in for danglers."""
+ return {"type": "object", "additionalProperties": True}
+
+
+def _is_mapping(value: t.Any) -> bool:
+ return isinstance(value, dict)
+
+
+def _decode_pointer_segment(segment: str) -> str:
+ # Order matters: ``~01`` must decode to ``~1`` (literal), not ``/``.
+ return segment.replace("~1", "/").replace("~0", "~")
+
+
+class _Resolution(t.NamedTuple):
+ ok: bool
+ value: t.Any = None
+ reason: t.Optional[UnresolvedRefReason] = None
+ failed_at: t.Optional[str] = None
+
+
+def _try_resolve_pointer(root: t.Dict[str, t.Any], pointer: str) -> _Resolution:
+ """Walk a local JSON Pointer (``#/a/b/0``) against ``root``.
+
+ Returns a tagged result so the caller can distinguish a malformed pointer
+ from a structurally valid pointer whose target is absent.
+ """
+ if pointer in ("#", ""):
+ return _Resolution(ok=True, value=root)
+ if not pointer.startswith("#/"):
+ return _Resolution(ok=False, reason="malformed-pointer")
+
+ cursor: t.Any = root
+ for raw_segment in pointer[2:].split("/"):
+ segment = _decode_pointer_segment(raw_segment)
+ if isinstance(cursor, list):
+ try:
+ index = int(segment)
+ except ValueError:
+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)
+ if index < 0 or index >= len(cursor):
+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)
+ cursor = cursor[index]
+ elif isinstance(cursor, dict):
+ if segment not in cursor:
+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)
+ cursor = cursor[segment]
+ else:
+ return _Resolution(ok=False, reason="missing-target", failed_at=segment)
+ return _Resolution(ok=True, value=cursor)
+
+
+def _raise_resolution_error(pointer: str, resolution: _Resolution) -> t.NoReturn:
+ if resolution.reason == "malformed-pointer":
+ raise JSONSchemaRefResolutionError(
+ f"Unsupported $ref pointer: {pointer}",
+ meta={"ref": pointer},
+ )
+ meta: t.Dict[str, t.Any] = {"ref": pointer}
+ if resolution.failed_at is not None:
+ meta["failed_at"] = resolution.failed_at
+ raise JSONSchemaRefResolutionError(
+ f"Cannot resolve $ref {pointer}",
+ meta=meta,
+ )
+
+
+def dereference_json_schema(
+ schema: t.Any,
+ *,
+ on_unresolved: UnresolvedRefStrategy = "throw",
+ on_replace: t.Optional[OnReplace] = None,
+) -> t.Any:
+ """Inline internal ``$ref`` pointers (``#/$defs/...`` and legacy
+ ``#/definitions/...``), returning a new schema; the input is never mutated.
+
+ External refs (``http://``, ``https://``, …) are left untouched (and logged
+ once for audit, since a downstream resolver fetching them could enable SSRF
+ or local-file disclosure). Cycles — both ``$ref`` cycles and JS-object-style
+ identity cycles — are broken with a permissive ``{"type": "object",
+ "additionalProperties": True}`` sentinel. ``$defs``/``definitions`` are
+ stripped from the returned root once everything is inlined.
+
+ :param on_unresolved: see :data:`UnresolvedRefStrategy`.
+ :param on_replace: invoked once per replaced node in ``"sentinel"`` mode,
+ with the original pointer and the reason it could not be resolved.
+ :raises JSONSchemaRefResolutionError: on malformed pointers or missing
+ targets (strict mode only), or chains/nesting past the safety caps
+ (both modes).
+ """
+ if not _is_mapping(schema):
+ return schema
+
+ root = t.cast(t.Dict[str, t.Any], schema)
+ # Identity-based cycle guard for the *current* walk path. Python doesn't
+ # suffer JS-style prototype pollution, so unlike the TS port there's no
+ # need to filter ``__proto__``/``constructor`` keys while cloning.
+ visiting: t.Set[int] = set()
+
+ # ``walk`` uses explicit loops (not comprehensions) so each level of schema
+ # nesting costs exactly one Python stack frame. That keeps ``MAX_NODE_DEPTH``
+ # the binding limit under the interpreter's default recursion ceiling, so a
+ # pathologically deep schema fails with our typed error rather than a bare
+ # ``RecursionError`` (which is also caught at the call site as a backstop).
+ def walk(
+ node: t.Any,
+ visited_refs: t.FrozenSet[str],
+ chain_depth: int,
+ node_depth: int,
+ ) -> t.Any:
+ if node_depth >= MAX_NODE_DEPTH:
+ raise JSONSchemaRefResolutionError(
+ f"JSON Schema node depth exceeded cap ({MAX_NODE_DEPTH})"
+ )
+
+ if isinstance(node, list):
+ node_id = id(node)
+ if node_id in visiting:
+ return _cycle_break_sentinel()
+ visiting.add(node_id)
+ try:
+ cloned_list: t.List[t.Any] = []
+ for item in node:
+ cloned_list.append(
+ walk(item, visited_refs, chain_depth, node_depth + 1)
+ )
+ return cloned_list
+ finally:
+ visiting.discard(node_id)
+
+ if not _is_mapping(node):
+ return node
+
+ node_id = id(node)
+ if node_id in visiting:
+ return _cycle_break_sentinel()
+ visiting.add(node_id)
+ try:
+ ref = node.get("$ref")
+ ref = ref if isinstance(ref, str) else None
+
+ # External refs and non-``$ref`` nodes both pass through the same
+ # reflective clone path.
+ if ref is None or not ref.startswith("#"):
+ if ref is not None:
+ logger.warning("Leaving external $ref untouched: %s", ref)
+ cloned: t.Dict[str, t.Any] = {}
+ for key, value in node.items():
+ cloned[key] = walk(value, visited_refs, chain_depth, node_depth + 1)
+ return cloned
+
+ if chain_depth >= MAX_REF_CHAIN_DEPTH:
+ raise JSONSchemaRefResolutionError(
+ f"JSON Schema $ref chain exceeded depth cap "
+ f"({MAX_REF_CHAIN_DEPTH}): {ref}",
+ meta={"ref": ref},
+ )
+ if ref in visited_refs:
+ return _cycle_break_sentinel()
+
+ resolution = _try_resolve_pointer(root, ref)
+ if resolution.ok:
+ target: t.Any = resolution.value
+ elif on_unresolved == "sentinel":
+ if on_replace is not None and resolution.reason is not None:
+ on_replace(ref, resolution.reason)
+ target = {
+ **_cycle_break_sentinel(),
+ "description": UNRESOLVED_REF_DESCRIPTION,
+ }
+ else:
+ _raise_resolution_error(ref, resolution)
+
+ next_refs = visited_refs | {ref}
+ resolved = walk(target, next_refs, chain_depth + 1, node_depth + 1)
+
+ # Shallow-merge sibling keywords next to ``$ref`` (Draft 2020-12:
+ # siblings win on collision). Draft 7 ignores them, but the Composio
+ # tool surface admits both, so we honor siblings for safety.
+ siblings = {key: value for key, value in node.items() if key != "$ref"}
+ if not siblings or not _is_mapping(resolved):
+ return resolved
+ merged = dict(resolved)
+ for key, value in siblings.items():
+ merged[key] = walk(value, visited_refs, chain_depth, node_depth + 1)
+ return merged
+ finally:
+ visiting.discard(node_id)
+
+ try:
+ out = walk(root, frozenset(), 0, 0)
+ except RecursionError as exc: # pragma: no cover - depth cap normally fires first
+ raise JSONSchemaRefResolutionError(
+ "JSON Schema nesting too deep to dereference"
+ ) from exc
+ if _is_mapping(out):
+ out.pop("$defs", None)
+ out.pop("definitions", None)
+ return out
diff --git a/python/tests/test_files.py b/python/tests/test_files.py
index 15b399b47..8db242b9a 100644
--- a/python/tests/test_files.py
+++ b/python/tests/test_files.py
@@ -336,6 +336,207 @@ class TestFileHelperSchemaHandling:
assert result == {"data": {"value": "test"}}
+class TestFileHelperRefDefsResolution:
+ """File flags reachable only through a $ref/$defs indirection.
+
+ Regression coverage for
+ https://github.com/ComposioHQ/composio/issues/3506. References are inlined
+ once at the public-method boundary (``dereference_json_schema``), so the
+ walkers themselves stay reference-agnostic.
+ """
+
+ @patch("composio.core.models._files.FileDownloadable.download")
+ def test_download_resolves_ref_defs(self, mock_download, file_helper, mock_tool):
+ """GMAIL_GET_ATTACHMENT shape: file_downloadable two $ref hops deep."""
+ mock_download.return_value = "/tmp/invoice.pdf"
+ mock_tool.output_parameters = {
+ "type": "object",
+ "$defs": {
+ "FileDownloadable": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string"},
+ "mimetype": {"type": "string"},
+ "s3url": {"type": "string"},
+ },
+ "required": ["name", "mimetype", "s3url"],
+ "file_downloadable": True,
+ },
+ "GetAttachmentResponse": {
+ "type": "object",
+ "properties": {
+ "file": {"$ref": "#/$defs/FileDownloadable"},
+ "display_url": {"type": "string"},
+ },
+ "required": ["file"],
+ },
+ },
+ "properties": {
+ "data": {"$ref": "#/$defs/GetAttachmentResponse"},
+ "successful": {"type": "boolean"},
+ },
+ "required": ["data", "successful"],
+ }
+ response = {
+ "data": {
+ "file": {
+ "name": "invoice.pdf",
+ "mimetype": "application/pdf",
+ "s3url": "https://s3.example.com/invoice.pdf",
+ },
+ "display_url": "https://mail.google.com/...",
+ },
+ "successful": True,
+ }
+
+ result = file_helper.substitute_file_downloads(
+ tool=mock_tool,
+ response=response,
+ )
+
+ assert result["data"]["file"] == "/tmp/invoice.pdf"
+ assert result["data"]["display_url"] == "https://mail.google.com/..."
+ assert result["successful"] is True
+ mock_download.assert_called_once()
+
+ @patch("composio.core.models._files.FileUploadable.from_path")
+ def test_upload_resolves_ref_defs(self, mock_from_path, file_helper, mock_tool):
+ """$ref/$defs input schema exposes a nested file_uploadable leaf."""
+ upload = MagicMock()
+ upload.model_dump.return_value = {
+ "name": "invoice.pdf",
+ "mimetype": "application/pdf",
+ "s3key": "uploads/invoice.pdf",
+ }
+ mock_from_path.return_value = upload
+ mock_tool.input_parameters = {
+ "type": "object",
+ "$defs": {
+ "FileUploadable": {"type": "string", "file_uploadable": True},
+ "AttachmentInput": {
+ "type": "object",
+ "properties": {
+ "file": {"$ref": "#/$defs/FileUploadable"},
+ "name": {"type": "string"},
+ },
+ "required": ["file"],
+ },
+ },
+ "properties": {"attachment": {"$ref": "#/$defs/AttachmentInput"}},
+ "required": ["attachment"],
+ }
+ request = {"attachment": {"file": "/local/invoice.pdf", "name": "invoice.pdf"}}
+
+ result = file_helper.substitute_file_uploads(
+ tool=mock_tool,
+ request=request,
+ )
+
+ assert result["attachment"]["file"] == {
+ "name": "invoice.pdf",
+ "mimetype": "application/pdf",
+ "s3key": "uploads/invoice.pdf",
+ }
+ assert result["attachment"]["name"] == "invoice.pdf"
+ mock_from_path.assert_called_once()
+
+ def test_process_file_uploadable_schema_resolves_ref_defs(self, file_helper):
+ """The LLM-facing input transform inlines $ref and rewrites the leaf."""
+ schema = {
+ "type": "object",
+ "$defs": {
+ "FileUploadable": {"type": "string", "file_uploadable": True},
+ "AttachmentInput": {
+ "type": "object",
+ "properties": {"file": {"$ref": "#/$defs/FileUploadable"}},
+ },
+ },
+ "properties": {"attachment": {"$ref": "#/$defs/AttachmentInput"}},
+ }
+
+ result = file_helper.process_file_uploadable_schema(schema)
+
+ leaf = result["properties"]["attachment"]["properties"]["file"]
+ assert leaf["type"] == "string"
+ assert leaf["format"] == "path"
+ assert leaf["file_uploadable"] is True
+ # $defs is inlined away; no dangling references remain.
+ assert "$defs" not in result
+ assert "$ref" not in result["properties"]["attachment"]
+
+ @patch("composio.core.models._files.FileDownloadable.download")
+ def test_dangling_ref_download_degrades_gracefully(
+ self, mock_download, file_helper, mock_tool
+ ):
+ """A $ref with no $defs block (issue #3307) must not raise (sentinel)."""
+ mock_tool.output_parameters = {
+ "type": "object",
+ "properties": {
+ "data": {"$ref": "#/$defs/Missing"},
+ "successful": {"type": "boolean"},
+ },
+ }
+ response = {"data": {"value": "passthrough"}, "successful": True}
+
+ # No $defs block at all: strict resolution would raise and abort the
+ # tool call. Sentinel mode keeps execution working — the unresolved
+ # branch is simply not treated as a file.
+ result = file_helper.substitute_file_downloads(
+ tool=mock_tool,
+ response=response,
+ )
+
+ assert result == {"data": {"value": "passthrough"}, "successful": True}
+ mock_download.assert_not_called()
+
+ @patch("composio.core.models._files.FileDownloadable.download")
+ def test_recursive_ref_schema_does_not_recurse_infinitely(
+ self, mock_download, file_helper, mock_tool
+ ):
+ """A self-referential $ref schema must not blow the stack.
+
+ A per-node lazy resolver without threaded cycle tracking infinite-loops
+ here; the centralized walker breaks the cycle with a sentinel.
+ """
+ mock_download.return_value = "/tmp/node.bin"
+ mock_tool.output_parameters = {
+ "type": "object",
+ "$defs": {
+ "Node": {
+ "type": "object",
+ "properties": {
+ "file": {
+ "type": "object",
+ "properties": {"s3url": {"type": "string"}},
+ "file_downloadable": True,
+ },
+ "child": {"$ref": "#/$defs/Node"},
+ },
+ },
+ },
+ "properties": {"root": {"$ref": "#/$defs/Node"}},
+ }
+ response = {
+ "root": {
+ "file": {
+ "name": "n.bin",
+ "mimetype": "application/octet-stream",
+ "s3url": "https://s3/x",
+ },
+ "child": {"value": "leaf"},
+ }
+ }
+
+ # Must complete without RecursionError.
+ result = file_helper.substitute_file_downloads(
+ tool=mock_tool,
+ response=response,
+ )
+
+ assert result["root"]["file"] == "/tmp/node.bin"
+ assert result["root"]["child"] == {"value": "leaf"}
+
+
class TestFileUploadableInUnionTypes:
"""Test cases for file_uploadable detection in anyOf, oneOf, and allOf schemas."""
diff --git a/python/tests/test_json_schema.py b/python/tests/test_json_schema.py
new file mode 100644
index 000000000..caad4c0b4
--- /dev/null
+++ b/python/tests/test_json_schema.py
@@ -0,0 +1,426 @@
+"""Tests for :func:`composio.utils.json_schema.dereference_json_schema`.
+
+Mirrors the TypeScript SDK's ``jsonSchema.test.ts`` so the two SDKs share one
+behavioral contract for inlining JSON Schema ``$ref`` pointers.
+"""
+
+import typing as t
+from unittest.mock import patch
+
+import pytest
+
+from composio.exceptions import JSONSchemaRefResolutionError
+from composio.utils import json_schema
+from composio.utils.json_schema import (
+ MAX_REF_CHAIN_DEPTH,
+ UNRESOLVED_REF_DESCRIPTION,
+ dereference_json_schema,
+)
+
+
+def _contains_ref(value: t.Any) -> bool:
+ if isinstance(value, dict):
+ if "$ref" in value:
+ return True
+ return any(_contains_ref(v) for v in value.values())
+ if isinstance(value, list):
+ return any(_contains_ref(v) for v in value)
+ return False
+
+
+PERMISSIVE: t.Dict[str, t.Any] = {"type": "object", "additionalProperties": True}
+PERMISSIVE_WITH_HINT: t.Dict[str, t.Any] = {
+ **PERMISSIVE,
+ "description": UNRESOLVED_REF_DESCRIPTION,
+}
+
+
+class TestDereferenceJsonSchema:
+ def test_inlines_single_internal_ref(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"user": {"$ref": "#/$defs/User"}},
+ "required": ["user"],
+ "$defs": {"User": {"type": "string"}},
+ }
+ )
+ assert out == {
+ "type": "object",
+ "properties": {"user": {"type": "string"}},
+ "required": ["user"],
+ }
+ assert _contains_ref(out) is False
+
+ def test_resolves_chain_a_b_c(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/A"}},
+ "$defs": {
+ "A": {"$ref": "#/$defs/B"},
+ "B": {"$ref": "#/$defs/C"},
+ "C": {"type": "integer"},
+ },
+ }
+ )
+ assert _contains_ref(out) is False
+ assert out["properties"]["v"] == {"type": "integer"}
+
+ def test_walks_containers_reflectively(self):
+ """Refs are resolved in keywords the file walkers never special-cased."""
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "a": {"type": "array", "items": {"$ref": "#/$defs/Leaf"}},
+ "b": {"oneOf": [{"$ref": "#/$defs/Leaf"}, {"type": "null"}]},
+ "c": {"anyOf": [{"$ref": "#/$defs/Leaf"}]},
+ "d": {"allOf": [{"$ref": "#/$defs/Leaf"}]},
+ "e": {"not": {"$ref": "#/$defs/Leaf"}},
+ "f": {
+ "type": "object",
+ "additionalProperties": {"$ref": "#/$defs/Leaf"},
+ },
+ "g": {
+ "type": "object",
+ "patternProperties": {"^x_": {"$ref": "#/$defs/Leaf"}},
+ },
+ "h": {"type": "array", "prefixItems": [{"$ref": "#/$defs/Leaf"}]},
+ },
+ "$defs": {"Leaf": {"type": "string"}},
+ }
+ )
+ assert _contains_ref(out) is False
+
+ def test_resolves_legacy_definitions(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"name": {"$ref": "#/definitions/Name"}},
+ "definitions": {"Name": {"type": "string", "minLength": 1}},
+ }
+ )
+ assert _contains_ref(out) is False
+ assert out["properties"]["name"] == {"type": "string", "minLength": 1}
+
+ def test_mixes_defs_and_definitions_transitively(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/definitions/A"}},
+ "definitions": {"A": {"$ref": "#/$defs/B"}},
+ "$defs": {"B": {"type": "boolean"}},
+ }
+ )
+ assert _contains_ref(out) is False
+ assert out["properties"]["v"] == {"type": "boolean"}
+
+ def test_sibling_keywords_win_on_collision(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "v": {
+ "$ref": "#/$defs/Foo",
+ "description": "caller override",
+ "default": None,
+ },
+ },
+ "$defs": {
+ "Foo": {"type": "string", "description": "target description"}
+ },
+ }
+ )
+ v = out["properties"]["v"]
+ assert v["type"] == "string"
+ assert v["description"] == "caller override"
+ assert v["default"] is None
+ assert _contains_ref(out) is False
+
+ def test_breaks_recursive_ref_cycles_with_sentinel(self):
+ out = dereference_json_schema(
+ {
+ "$ref": "#/$defs/Tree",
+ "$defs": {
+ "Tree": {
+ "type": "object",
+ "properties": {
+ "children": {
+ "type": "array",
+ "items": {"$ref": "#/$defs/Tree"},
+ },
+ },
+ },
+ },
+ }
+ )
+ assert out["type"] == "object"
+ assert out["properties"]["children"]["items"] == PERMISSIVE
+ assert _contains_ref(out) is False
+
+ def test_strips_defs_and_definitions_from_root(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"x": {"$ref": "#/$defs/Foo"}},
+ "$defs": {"Foo": {"type": "integer"}},
+ "definitions": {"Bar": {"type": "string"}},
+ }
+ )
+ assert "$defs" not in out
+ assert "definitions" not in out
+
+ def test_throws_when_target_missing(self):
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
+ "$defs": {},
+ }
+ )
+
+ def test_throws_when_chain_depth_exceeds_cap(self):
+ defs: t.Dict[str, t.Any] = {}
+ for i in range(200):
+ target = f"#/$defs/A{i + 1}" if i + 1 < 200 else "#/$defs/A0"
+ defs[f"A{i}"] = {"$ref": target}
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/A0"}},
+ "$defs": defs,
+ }
+ )
+
+ def test_throws_on_pathologically_deep_nesting(self):
+ leaf: t.Dict[str, t.Any] = {"type": "string"}
+ for _ in range(1000):
+ leaf = {"type": "object", "properties": {"x": leaf}}
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(leaf)
+
+ def test_breaks_identity_cycles_without_ref(self):
+ """A live-object cycle that does not flow through a ``$ref``."""
+ root: t.Dict[str, t.Any] = {"type": "object", "properties": {}}
+ root["properties"]["self"] = root
+ out = dereference_json_schema(root)
+ assert out["properties"]["self"] == PERMISSIVE
+
+ def test_leaves_external_ref_untouched_and_warns(self):
+ with patch.object(json_schema.logger, "warning") as warn:
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "https://example.com/Foo"}},
+ }
+ )
+ assert out["properties"]["v"]["$ref"] == "https://example.com/Foo"
+ warn.assert_called_once()
+ assert "https://example.com/Foo" in str(warn.call_args)
+
+ def test_does_not_mutate_input(self):
+ import copy
+
+ schema = {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/Foo"}},
+ "$defs": {"Foo": {"type": "string"}},
+ }
+ snapshot = copy.deepcopy(schema)
+ dereference_json_schema(schema)
+ assert schema == snapshot
+
+ def test_decodes_json_pointer_escapes(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "a": {"$ref": "#/$defs/with~1slash"},
+ "b": {"$ref": "#/$defs/with~0tilde"},
+ "c": {"$ref": "#/$defs/tilde-then-slash~01"},
+ },
+ "$defs": {
+ "with/slash": {"type": "string"},
+ "with~tilde": {"type": "integer"},
+ "tilde-then-slash~1": {"type": "boolean"},
+ },
+ }
+ )
+ props = out["properties"]
+ assert props["a"]["type"] == "string"
+ assert props["b"]["type"] == "integer"
+ assert props["c"]["type"] == "boolean"
+
+ def test_resolves_array_index_pointers(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/foo/oneOf/0"}},
+ "$defs": {"foo": {"oneOf": [{"type": "string"}, {"type": "number"}]}},
+ }
+ )
+ assert out["properties"]["v"]["type"] == "string"
+
+ def test_passthrough_for_non_dict_input(self):
+ assert dereference_json_schema("not-a-schema") == "not-a-schema"
+ assert dereference_json_schema(None) is None
+
+
+class TestSentinelMode:
+ def test_replaces_dangling_ref_with_no_defs_block(self):
+ """Mirrors GMAIL_FETCH_EMAILS: a ``$ref`` into ``#/$defs`` with no defs."""
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "data": {"$ref": "#/$defs/FetchEmailsResponse"},
+ "error": {"type": "string"},
+ "successful": {"type": "boolean"},
+ },
+ "required": ["data", "successful"],
+ "title": "FetchEmailsResponseWrapper",
+ },
+ on_unresolved="sentinel",
+ )
+ assert out["properties"]["data"] == PERMISSIVE_WITH_HINT
+ assert out["properties"]["error"] == {"type": "string"}
+ assert out["properties"]["successful"] == {"type": "boolean"}
+ assert out["required"] == ["data", "successful"]
+ assert _contains_ref(out) is False
+
+ def test_replaces_ref_into_empty_defs(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
+ "$defs": {},
+ },
+ on_unresolved="sentinel",
+ )
+ assert out["properties"]["v"] == PERMISSIVE_WITH_HINT
+ assert _contains_ref(out) is False
+
+ def test_on_replace_called_once_per_replacement(self):
+ calls: t.List[t.Tuple[str, str]] = []
+ dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "a": {"$ref": "#/$defs/Missing"},
+ "b": {"$ref": "#/$defs/Missing"},
+ "c": {"$ref": "#/$defs/AlsoMissing"},
+ },
+ },
+ on_unresolved="sentinel",
+ on_replace=lambda ref, reason: calls.append((ref, reason)),
+ )
+ assert calls == [
+ ("#/$defs/Missing", "missing-target"),
+ ("#/$defs/Missing", "missing-target"),
+ ("#/$defs/AlsoMissing", "missing-target"),
+ ]
+
+ def test_on_replace_malformed_pointer(self):
+ calls: t.List[t.Tuple[str, str]] = []
+ out = dereference_json_schema(
+ {"type": "object", "properties": {"v": {"$ref": "#bar"}}},
+ on_unresolved="sentinel",
+ on_replace=lambda ref, reason: calls.append((ref, reason)),
+ )
+ assert calls == [("#bar", "malformed-pointer")]
+ assert out["properties"]["v"] == PERMISSIVE_WITH_HINT
+
+ def test_still_throws_on_chain_depth_cap(self):
+ defs: t.Dict[str, t.Any] = {}
+ for i in range(200):
+ target = f"#/$defs/A{i + 1}" if i + 1 < 200 else "#/$defs/A0"
+ defs[f"A{i}"] = {"$ref": target}
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/A0"}},
+ "$defs": defs,
+ },
+ on_unresolved="sentinel",
+ )
+
+ def test_still_throws_on_node_depth_cap(self):
+ leaf: t.Dict[str, t.Any] = {"type": "string"}
+ for _ in range(1000):
+ leaf = {"type": "object", "properties": {"x": leaf}}
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(leaf, on_unresolved="sentinel")
+
+ def test_explicit_throw_matches_default(self):
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
+ "$defs": {},
+ },
+ on_unresolved="throw",
+ )
+
+ def test_does_not_call_on_replace_in_strict_mode(self):
+ calls: t.List[t.Any] = []
+ with pytest.raises(JSONSchemaRefResolutionError):
+ dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {"v": {"$ref": "#/$defs/Missing"}},
+ "$defs": {},
+ },
+ on_unresolved="throw",
+ on_replace=lambda ref, reason: calls.append((ref, reason)),
+ )
+ assert calls == []
+
+ def test_injects_default_description_when_no_sibling(self):
+ out = dereference_json_schema(
+ {"type": "object", "properties": {"v": {"$ref": "#/$defs/Missing"}}},
+ on_unresolved="sentinel",
+ )
+ description = out["properties"]["v"]["description"]
+ assert "Schema shape unresolved at the source" in description
+ assert "https://github.com/ComposioHQ/composio/issues/3307" in description
+
+ def test_preserves_caller_description_sibling(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "v": {
+ "$ref": "#/$defs/Missing",
+ "description": "caller-supplied prose context",
+ },
+ },
+ },
+ on_unresolved="sentinel",
+ )
+ assert out["properties"]["v"]["description"] == "caller-supplied prose context"
+ assert out["properties"]["v"]["type"] == "object"
+
+ def test_preserves_resolvable_defs_while_replacing_dangling_branch(self):
+ out = dereference_json_schema(
+ {
+ "type": "object",
+ "properties": {
+ "resolved": {"$ref": "#/$defs/Real"},
+ "dangling": {"$ref": "#/$defs/Ghost"},
+ },
+ "$defs": {"Real": {"type": "integer"}},
+ },
+ on_unresolved="sentinel",
+ )
+ assert out["properties"]["resolved"] == {"type": "integer"}
+ assert out["properties"]["dangling"] == PERMISSIVE_WITH_HINT
+
+
+def test_max_ref_chain_depth_is_exposed():
+ """Guard against accidental removal of the safety cap constant."""
+ assert MAX_REF_CHAIN_DEPTH == 100