Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Build client schema types with create_model and bounded caches (#5413)

Jeremiah Lowin35bb8b9e0785
diff --git a/fastmcp_slim/fastmcp/client/mixins/tools.py b/fastmcp_slim/fastmcp/client/mixins/tools.py
index 1a7ed104a..10043d7cc 100644
--- a/fastmcp_slim/fastmcp/client/mixins/tools.py
+++ b/fastmcp_slim/fastmcp/client/mixins/tools.py
@@ -16,10 +16,9 @@ from fastmcp.client.progress import ProgressHandler
from fastmcp.client.telemetry import client_span
from fastmcp.exceptions import ToolError
from fastmcp.telemetry import inject_trace_context
-from fastmcp.utilities.json_schema_type import json_schema_to_type
+from fastmcp.utilities.json_schema_type import json_schema_to_type_adapter
from fastmcp.utilities.logging import get_logger
from fastmcp.utilities.timeout import normalize_timeout_to_seconds
-from fastmcp.utilities.types import get_cached_typeadapter
logger = get_logger(__name__)
@@ -405,8 +404,7 @@ async def _parse_call_tool_result(
output_schema = output_schema.get("properties", {}).get(
"result", output_schema
)
- output_type = json_schema_to_type(output_schema)
- type_adapter = get_cached_typeadapter(output_type)
+ type_adapter = json_schema_to_type_adapter(output_schema)
data = type_adapter.validate_python(structured_content)
else:
data = structured_content
diff --git a/fastmcp_slim/fastmcp/utilities/json_schema_type.py b/fastmcp_slim/fastmcp/utilities/json_schema_type.py
index a16fa65a8..8aaf58988 100644
--- a/fastmcp_slim/fastmcp/utilities/json_schema_type.py
+++ b/fastmcp_slim/fastmcp/utilities/json_schema_type.py
@@ -57,17 +57,22 @@ import json
import keyword
import re
import sys
+import threading
import warnings
-from collections.abc import Callable, Mapping
+from collections import OrderedDict
+from collections.abc import Callable, Hashable, Mapping
+from contextvars import ContextVar
from copy import deepcopy
-from dataclasses import MISSING, field, make_dataclass
+from dataclasses import MISSING, dataclass, field, make_dataclass
from datetime import date, datetime
from functools import lru_cache
from typing import (
Annotated,
Any,
ForwardRef,
+ Generic,
Literal,
+ TypeVar,
Union,
cast,
)
@@ -82,8 +87,10 @@ from pydantic import (
Json,
StringConstraints,
TypeAdapter,
+ create_model,
model_validator,
)
+from pydantic.fields import FieldInfo
from pydantic_core import SchemaError as _PydanticSchemaError
from typing_extensions import NotRequired, TypedDict
@@ -127,7 +134,86 @@ FORMAT_TYPES: dict[str, Any] = {
"json": Json,
}
-_classes: dict[tuple[str, Any], type | None] = {}
+_V = TypeVar("_V")
+
+
+class _LRUCache(Generic[_V]):
+ """Least recently used cache bounded by entry count and total weight.
+
+ Each entry's weight is the serialized size of the whole schema the
+ conversion started from. A generated class refers to the classes of its
+ properties and keeps the schema it was built from, so it retains as much
+ as the root schema describes. Charging that size keeps the total memory
+ held by the cache within `max_weight`. An entry heavier than `max_weight`
+ is not stored.
+ """
+
+ def __init__(self, max_entries: int, max_weight: int) -> None:
+ self.max_entries = max_entries
+ self.max_weight = max_weight
+ self._items: OrderedDict[Hashable, tuple[_V, int]] = OrderedDict()
+ self._weight = 0
+ self._lock = threading.Lock()
+
+ def get(self, key: Hashable) -> _V | None:
+ with self._lock:
+ item = self._items.get(key)
+ if item is None:
+ return None
+ self._items.move_to_end(key)
+ return item[0]
+
+ def put(self, key: Hashable, value: _V, weight: int) -> None:
+ with self._lock:
+ previous = self._items.pop(key, None)
+ if previous is not None:
+ self._weight -= previous[1]
+ if weight > self.max_weight:
+ return
+ self._items[key] = (value, weight)
+ self._weight += weight
+ while len(self._items) > self.max_entries or self._weight > self.max_weight:
+ _, (_, evicted_weight) = self._items.popitem(last=False)
+ self._weight -= evicted_weight
+
+ def clear(self) -> None:
+ with self._lock:
+ self._items.clear()
+ self._weight = 0
+
+ def __len__(self) -> int:
+ return len(self._items)
+
+
+# Generated classes keyed by (schema hash + root schema hash, class name). Each
+# class is weighted by the size of its root schema, so a conversion whose root
+# is larger than the weight limit adds nothing to the cache.
+_classes: _LRUCache[type] = _LRUCache(max_entries=5000, max_weight=4_000_000)
+# TypeAdapters for whole schemas, keyed by schema hash. They hold their
+# classes, so they are bounded the same way.
+_adapters: _LRUCache[TypeAdapter[Any]] = _LRUCache(
+ max_entries=1000, max_weight=4_000_000
+)
+
+# Limits on a single conversion. Depth counts nested schemas and `$ref` hops;
+# steps count every schema visited.
+_MAX_CONVERSION_DEPTH = 64
+_MAX_CONVERSION_STEPS = 50_000
+
+
+@dataclass
+class _Conversion:
+ """State for one `json_schema_to_type` call."""
+
+ root_hash: str
+ root_size: int
+ resolved_refs: dict[str, Any] = field(default_factory=dict)
+ building: set[tuple[str, str]] = field(default_factory=set)
+ depth: int = 0
+ steps: int = 0
+
+
+_conversion: ContextVar[_Conversion] = ContextVar("json_schema_conversion")
class JSONSchema(TypedDict):
@@ -180,7 +266,8 @@ def json_schema_to_type(
A Python type (typically a dataclass for objects) with Pydantic validation
Raises:
- ValueError: If a name is provided for a non-object schema
+ ValueError: If a name is provided for a non-object schema, or if the
+ schema is too deeply nested or too large to convert.
Examples:
Create a dataclass from an object schema:
@@ -232,17 +319,41 @@ def json_schema_to_type(
# so that downstream json.dumps/hashing and default values work correctly.
schema = _normalize_yaml_types(schema)
- # Always use the top-level schema for references
- if schema.get("type") == "object":
- return _object_schema_to_type(schema, schemas=schema, name=name)
- elif name:
- raise ValueError(f"Can not apply name to non-object schema: {name}")
- result = _schema_to_type(schema, schemas=schema)
- return result # type: ignore[return-value] # ty:ignore[invalid-return-type]
+ root_hash, root_size = _schema_digest(schema)
+ token = _conversion.set(_Conversion(root_hash=root_hash, root_size=root_size))
+ try:
+ # Always use the top-level schema for references
+ if schema.get("type") == "object":
+ return _object_schema_to_type(schema, schemas=schema, name=name)
+ elif name:
+ raise ValueError(f"Can not apply name to non-object schema: {name}")
+ result = _schema_to_type(schema, schemas=schema)
+ return result # type: ignore[return-value] # ty:ignore[invalid-return-type]
+ finally:
+ _conversion.reset(token)
+
+
+def json_schema_to_type_adapter(schema: Mapping[str, Any] | bool) -> TypeAdapter[Any]:
+ """Return a cached `TypeAdapter` for `json_schema_to_type(schema)`.
+
+ Adapters are cached by schema content in a bounded cache, so the classes
+ they hold are released when they are evicted.
+ """
+ key, size = _schema_digest(schema)
+ adapter = _adapters.get(key)
+ if adapter is None:
+ adapter = TypeAdapter(json_schema_to_type(schema))
+ _adapters.put(key, adapter, size)
+ return adapter
def _hash_schema(schema: Mapping[str, Any]) -> str:
- """Generate a deterministic hash for schema caching.
+ """Generate a deterministic hash for schema caching."""
+ return _schema_digest(schema)[0]
+
+
+def _schema_digest(schema: Mapping[str, Any] | bool) -> tuple[str, int]:
+ """Return a deterministic hash of the schema and its serialized size.
Handles non-JSON-native types (datetime, date, bool keys) that can
appear in schemas loaded from YAML, which auto-parses date strings.
@@ -254,7 +365,8 @@ def _hash_schema(schema: Mapping[str, Any]) -> str:
except TypeError:
# Mixed key types (bool + str) can't be sorted; fall back
raw = json.dumps(schema, default=str)
- return hashlib.sha256(raw.encode()).hexdigest()
+ encoded = raw.encode()
+ return hashlib.sha256(encoded).hexdigest(), len(encoded)
def _resolve_ref(ref: str, schemas: Mapping[str, Any]) -> Mapping[str, Any]:
@@ -489,7 +601,25 @@ def _schema_to_type(
schemas: Mapping[str, Any],
resolving_refs: frozenset[str] = frozenset(),
) -> type | ForwardRef:
- """Convert schema to appropriate Python type."""
+ """Convert schema to appropriate Python type, within the conversion limits."""
+ conversion = _conversion.get()
+ conversion.steps += 1
+ if conversion.depth >= _MAX_CONVERSION_DEPTH:
+ raise ValueError("JSON schema is too deeply nested to convert")
+ if conversion.steps > _MAX_CONVERSION_STEPS:
+ raise ValueError("JSON schema is too large to convert")
+ conversion.depth += 1
+ try:
+ return _convert_schema(schema, schemas, resolving_refs)
+ finally:
+ conversion.depth -= 1
+
+
+def _convert_schema(
+ schema: Mapping[str, Any] | bool,
+ schemas: Mapping[str, Any],
+ resolving_refs: frozenset[str],
+) -> type | ForwardRef:
# Boolean schemas are valid in JSON Schema draft-06+:
# true means "any value is valid" (equivalent to {}),
# false means "no value is valid" (unsatisfiable).
@@ -509,7 +639,7 @@ def _schema_to_type(
ref = schema["$ref"]
# Handle self-reference
if ref == "#":
- return ForwardRef(schema.get("title", "Root"))
+ return ForwardRef(_sanitize_name(schema.get("title", "Root")))
if ref in resolving_refs:
resolved = _resolve_ref(ref, schemas)
if isinstance(resolved, Mapping) and (
@@ -517,9 +647,14 @@ def _schema_to_type(
):
return _schema_to_type(resolved, schemas, resolving_refs)
return Any
- return _schema_to_type(
- _resolve_ref(ref, schemas), schemas, resolving_refs | {ref}
- )
+ # Convert each reference once per conversion, so a definition shared
+ # by many references is not expanded again for every path to it.
+ resolved_refs = _conversion.get().resolved_refs
+ if ref not in resolved_refs:
+ resolved_refs[ref] = _schema_to_type(
+ _resolve_ref(ref, schemas), schemas, resolving_refs | {ref}
+ )
+ return resolved_refs[ref]
if "const" in schema:
return Literal[schema["const"]] # type: ignore
@@ -542,7 +677,7 @@ def _schema_to_type(
return type(None)
elif len(types) == 1:
if has_null:
- return types[0] | None # type: ignore
+ return Union[types[0], type(None)] # type: ignore # noqa: UP007
else:
return types[0]
else:
@@ -566,7 +701,7 @@ def _schema_to_type(
types = [t for t in types if t is not type(None)]
if has_null:
if len(types) == 1:
- return types[0] | None # type: ignore
+ return Union[types[0], type(None)] # type: ignore # noqa: UP007
else:
return Union[(*types, type(None))] # type: ignore
return Union[tuple(types)] # type: ignore # noqa: UP007
@@ -595,6 +730,58 @@ def _sanitize_name(name: str) -> str:
return cleaned
+_BASE_MODEL_MEMBERS = frozenset(dir(BaseModel))
+
+
+def _is_reserved_field_name(name: str) -> bool:
+ """Whether a property name would act as a class or Pydantic control name.
+
+ Leading underscores cover dunders, Pydantic private attributes, and the
+ `create_model` keyword arguments. Members in the `model_` namespace are
+ Pydantic's own API.
+ """
+ return name.startswith("_") or (
+ name.startswith("model_") and name in _BASE_MODEL_MEMBERS
+ )
+
+
+def safe_create_model(
+ name: str,
+ field_definitions: Mapping[str, tuple[Any, Any]],
+ *,
+ config: ConfigDict | None = None,
+) -> type[BaseModel]:
+ """Create a Pydantic model whose field names come from untrusted input.
+
+ Each property name only ever becomes a field. A reserved name is stored
+ under a generated field name with the original name as its alias, so it
+ validates and dumps (with `by_alias=True`) under its original name.
+
+ Args:
+ name: The model class name.
+ field_definitions: Maps each property name to `(annotation, default)`,
+ where `default` may be a `FieldInfo` or `...` for required fields.
+ config: Optional model configuration.
+ """
+ fields: dict[str, Any] = {}
+ for prop_name, (annotation, default) in field_definitions.items():
+ field_name = prop_name
+ if _is_reserved_field_name(prop_name):
+ base = f"field_{_sanitize_name(prop_name).lstrip('_')}"
+ field_name = base
+ counter = 2
+ while field_name in fields or field_name in field_definitions:
+ field_name = f"{base}_{counter}"
+ counter += 1
+ if isinstance(default, FieldInfo):
+ annotation = Annotated[annotation, default]
+ default = Field(alias=prop_name)
+ else:
+ default = Field(default=default, alias=prop_name)
+ fields[field_name] = (annotation, default)
+ return create_model(name, __config__=config, **fields)
+
+
def _get_default_value(
schema: dict[str, Any],
prop_name: str,
@@ -635,58 +822,58 @@ def _create_pydantic_model(
if name is None:
raise ValueError("Name is required")
sanitized_name = _sanitize_name(name)
+ conversion = _conversion.get()
schema_hash = _hash_schema(schema)
- cache_key = (schema_hash, sanitized_name)
+ cache_key = (schema_hash + conversion.root_hash, sanitized_name)
# Return existing class if already built
- if cache_key in _classes:
- existing = _classes[cache_key]
- if existing is None:
- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]
+ existing = _classes.get(cache_key)
+ if existing is not None:
return existing
+ # A recursive reference to a class that is still being built
+ if cache_key in conversion.building:
+ return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]
+
+ conversion.building.add(cache_key)
+ try:
+ cls = _build_pydantic_model(
+ schema, sanitized_name, schemas or {}, resolving_refs
+ )
+ finally:
+ conversion.building.discard(cache_key)
+ _classes.put(cache_key, cls, conversion.root_size)
+ return cls
- # Place placeholder for recursive references
- _classes[cache_key] = None
+def _build_pydantic_model(
+ schema: Mapping[str, Any],
+ name: str,
+ schemas: Mapping[str, Any],
+ resolving_refs: frozenset[str],
+) -> type:
properties = schema.get("properties", {})
required = schema.get("required", [])
- # Build field annotations and defaults
- annotations = {}
- defaults = {}
-
+ field_definitions: dict[str, tuple[Any, Any]] = {}
for prop_name, prop_schema in properties.items():
# Boolean schemas (JSON Schema draft-06+): resolve type directly,
# then use an empty dict for .get() calls below.
if isinstance(prop_schema, bool):
- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)
prop_schema = {}
else:
- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)
# Handle defaults
default_value = prop_schema.get("default", MISSING)
if default_value is not MISSING:
- defaults[prop_name] = default_value
- annotations[prop_name] = field_type
+ field_definitions[prop_name] = (field_type, default_value)
elif prop_name in required:
- annotations[prop_name] = field_type
+ field_definitions[prop_name] = (field_type, ...)
else:
- annotations[prop_name] = Union[field_type, type(None)] # type: ignore[misc] # noqa: UP007 # ty:ignore[invalid-type-form]
- defaults[prop_name] = None
-
- # Create Pydantic model class
- cls_dict = {
- "__annotations__": annotations,
- "model_config": ConfigDict(extra="allow"),
- **defaults,
- }
+ field_definitions[prop_name] = (Union[field_type, type(None)], None) # type: ignore[misc] # noqa: UP007 # ty:ignore[invalid-type-form]
- cls = type(sanitized_name, (BaseModel,), cls_dict)
-
- # Store completed class
- _classes[cache_key] = cls
- return cls
+ return safe_create_model(name, field_definitions, config=ConfigDict(extra="allow"))
def _create_dataclass(
@@ -701,27 +888,43 @@ def _create_dataclass(
if name is None:
raise ValueError("Name is required")
sanitized_name = _sanitize_name(name)
+ conversion = _conversion.get()
schema_hash = _hash_schema(schema)
- cache_key = (schema_hash, sanitized_name)
- original_schema = dict(schema) # Store copy for validator
+ cache_key = (schema_hash + conversion.root_hash, sanitized_name)
# Return existing class if already built
- if cache_key in _classes:
- existing = _classes[cache_key]
- if existing is None:
- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]
+ existing = _classes.get(cache_key)
+ if existing is not None:
return existing
+ # A recursive reference to a class that is still being built
+ if cache_key in conversion.building:
+ return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]
+
+ conversion.building.add(cache_key)
+ try:
+ cls = _build_dataclass(schema, sanitized_name, schemas or {}, resolving_refs)
+ finally:
+ conversion.building.discard(cache_key)
+ if isinstance(cls, type):
+ _classes.put(cache_key, cls, conversion.root_size)
+ return cls
- # Place placeholder for recursive references
- _classes[cache_key] = None
+
+def _build_dataclass(
+ schema: Mapping[str, Any],
+ sanitized_name: str,
+ schemas: Mapping[str, Any],
+ resolving_refs: frozenset[str],
+) -> Any:
+ original_schema = dict(schema) # Store copy for validator
if "$ref" in schema:
ref = schema["$ref"]
if ref == "#":
- return ForwardRef(sanitized_name) # type: ignore[return-value] # ty:ignore[invalid-return-type]
+ return ForwardRef(sanitized_name)
if ref in resolving_refs:
return Any
- schema = _resolve_ref(ref, schemas or {})
+ schema = _resolve_ref(ref, schemas)
resolving_refs = resolving_refs | {ref}
properties = schema.get("properties", {})
@@ -743,13 +946,13 @@ def _create_dataclass(
# Boolean schemas (JSON Schema draft-06+): resolve type directly,
# then use an empty dict for .get() calls below.
if isinstance(prop_schema, bool):
- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)
prop_schema = {}
elif prop_schema.get("$ref") == "#":
# Check for self-reference in property
field_type = ForwardRef(sanitized_name)
else:
- field_type = _schema_to_type(prop_schema, schemas or {}, resolving_refs)
+ field_type = _schema_to_type(prop_schema, schemas, resolving_refs)
default_val = prop_schema.get("default", MISSING)
is_required = prop_name in required
@@ -786,9 +989,6 @@ def _create_dataclass(
return data
cls._apply_defaults = _apply_defaults # type: ignore[attr-defined] # ty:ignore[unresolved-attribute]
-
- # Store completed class
- _classes[cache_key] = cls
return cls
diff --git a/loq.toml b/loq.toml
index 654c59997..fb31aebe9 100644
--- a/loq.toml
+++ b/loq.toml
@@ -65,3 +65,7 @@ max_lines = 1185
[[rules]]
path = "tests/utilities/openapi/test_director.py"
max_lines = 1154
+
+[[rules]]
+path = "fastmcp_slim/fastmcp/utilities/json_schema_type.py"
+max_lines = 1059
diff --git a/tests/utilities/json_schema_type/test_generated_classes.py b/tests/utilities/json_schema_type/test_generated_classes.py
new file mode 100644
index 000000000..a685a8c96
--- /dev/null
+++ b/tests/utilities/json_schema_type/test_generated_classes.py
@@ -0,0 +1,710 @@
+"""Generated class names, field aliases, conversion limits, and the class cache."""
+
+import gc
+import json
+import keyword
+import weakref
+from typing import Any
+
+import pytest
+from pydantic import BaseModel, Field, TypeAdapter, ValidationError
+from pydantic.fields import FieldInfo
+
+from fastmcp import Client, Context, FastMCP
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.tools import ToolResult
+from fastmcp.utilities import json_schema_type
+from fastmcp.utilities.json_schema_type import (
+ json_schema_to_type,
+ json_schema_to_type_adapter,
+ safe_create_model,
+)
+
+TITLE = "Order Item (v2)"
+
+
+def order_item_schema(children: dict[str, Any], title: str = TITLE) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "title": title,
+ "properties": {"name": {"type": "string"}, "children": children},
+ }
+
+
+def nested_items_schema(title: str) -> dict[str, Any]:
+ self_reference = {"$ref": "#", "title": title}
+ return order_item_schema({"type": "array", "items": self_reference}, title)
+
+
+NESTED_ITEMS_VALUE = {"name": "a", "children": [{"name": "b"}]}
+
+AWKWARD_TITLES = {
+ "parenthesized_version": "Order Item (v2)",
+ "double_quotes": 'Item "A"',
+ "apostrophe": "it's an item",
+ "dot_and_slash": "a.b/c",
+ "keyword": "class",
+ "none_keyword": "None",
+ "leading_digit": "3d model",
+ "non_ascii": "名前",
+ "empty": "",
+ "very_long": "Item " * 60,
+ "newline_and_tab": "Item\nOne\tTwo",
+ "dunder": "__init__",
+ "call_syntax": "Item(1)",
+ "subscript_syntax": "list[str]",
+ "boolean_words": "a or b",
+ "conditional_words": "x if y else z",
+ "lambda_words": "lambda: 0",
+ "semicolon": "a; b",
+ "hash_sign": "item#1",
+ "trailing_backslash": "Item\\",
+ "only_punctuation": "!!!",
+}
+
+
+SELF_REFERENCE = {"$ref": "#", "title": TITLE}
+NESTED_ORDER_ITEMS = order_item_schema({"type": "array", "items": SELF_REFERENCE})
+RESERVED_PROPERTIES = {
+ "type": "object",
+ "additionalProperties": True,
+ "properties": {
+ "model_config": {"type": "string"},
+ "_private": {"type": "string"},
+ "name": {"type": "string"},
+ },
+}
+
+
+class TestDescriptiveTitles:
+ def test_title_becomes_valid_class_name(self):
+ generated = json_schema_to_type(NESTED_ORDER_ITEMS)
+
+ assert generated.__name__ == "Order_Item_v2"
+
+ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)
+ def test_any_title_becomes_valid_class_name(self, title: str):
+ generated = json_schema_to_type(nested_items_schema(title))
+
+ assert generated.__name__.isidentifier()
+ assert not keyword.iskeyword(generated.__name__)
+
+ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)
+ def test_any_title_supports_nested_self_reference(self, title: str):
+ generated = json_schema_to_type(nested_items_schema(title))
+
+ item = TypeAdapter(generated).validate_python(NESTED_ITEMS_VALUE)
+
+ child = item.children[0] # ty: ignore[unresolved-attribute]
+ assert isinstance(child, generated)
+ assert child.name == "b"
+
+ @pytest.mark.parametrize(
+ "title,expected",
+ [
+ ("class", "class_"),
+ ("None", "None_"),
+ ("3d model", "field_3d_model"),
+ ("", "field"),
+ ("!!!", "field"),
+ ("list[str]", "list_str"),
+ ("Item(1)", "Item_1"),
+ ],
+ )
+ def test_title_class_names(self, title: str, expected: str):
+ generated = json_schema_to_type(nested_items_schema(title))
+
+ assert generated.__name__ == expected
+
+ @pytest.mark.parametrize(
+ "children,value",
+ [
+ ({"type": "array", "items": SELF_REFERENCE}, [{"name": "b"}]),
+ ({"anyOf": [SELF_REFERENCE, {"type": "null"}]}, {"name": "b"}),
+ (
+ {"type": "object", "additionalProperties": SELF_REFERENCE},
+ {"first": {"name": "b"}},
+ ),
+ ({"type": ["array", "null"], "items": SELF_REFERENCE}, [{"name": "b"}]),
+ ],
+ ids=["array", "union", "map", "type_list"],
+ )
+ def test_nested_self_reference_validates(
+ self, children: dict[str, Any], value: Any
+ ):
+ generated = json_schema_to_type(order_item_schema(children))
+
+ item = TypeAdapter(generated).validate_python({"name": "a", "children": value})
+
+ nested = item.children # ty: ignore[unresolved-attribute]
+ child = nested["first"] if isinstance(nested, dict) else nested
+ child = child[0] if isinstance(child, list) else child
+ assert isinstance(child, generated)
+ assert child.name == "b"
+
+
+class TestClientSchemas:
+ async def test_tool_output_with_self_reference(self):
+ server = FastMCP("Orders")
+
+ @server.tool(output_schema=NESTED_ORDER_ITEMS)
+ def order() -> ToolResult:
+ return ToolResult(
+ structured_content={"name": "a", "children": [{"name": "b"}]}
+ )
+
+ async with Client(server) as client:
+ result = await client.call_tool("order", {})
+
+ assert type(result.data).__name__ == "Order_Item_v2"
+ assert result.data.children[0].name == "b"
+
+ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)
+ async def test_tool_output_with_any_title(self, title: str):
+ server = FastMCP("Orders")
+
+ @server.tool(output_schema=nested_items_schema(title))
+ def order() -> ToolResult:
+ return ToolResult(structured_content=NESTED_ITEMS_VALUE)
+
+ async with Client(server) as client:
+ result = await client.call_tool("order", {})
+
+ assert type(result.data).__name__.isidentifier()
+ assert not keyword.iskeyword(type(result.data).__name__)
+ child = result.data.children[0]
+ assert isinstance(child, type(result.data))
+ assert child.name == "b"
+
+ async def test_tool_output_with_reserved_property_names(self):
+ server = FastMCP("Settings")
+ content = {"model_config": "strict", "_private": "x", "name": "a"}
+
+ @server.tool(output_schema=RESERVED_PROPERTIES)
+ def settings() -> ToolResult:
+ return ToolResult(structured_content=content)
+
+ async with Client(server) as client:
+ result = await client.call_tool("settings", {})
+
+ assert isinstance(result.data, BaseModel)
+ assert result.data.model_dump(by_alias=True) == content
+
+ @pytest.mark.parametrize(
+ "schema,content",
+ [
+ (NESTED_ORDER_ITEMS, {"name": "a", "children": [{"name": "b"}]}),
+ (RESERVED_PROPERTIES, {"model_config": "strict", "name": "a"}),
+ ],
+ ids=["self_reference", "reserved_property_names"],
+ )
+ async def test_elicitation_schema(
+ self, schema: dict[str, Any], content: dict[str, Any]
+ ):
+ server = FastMCP("Forms")
+ validated: list[Any] = []
+
+ @server.tool
+ async def ask(ctx: Context) -> str:
+ response = await ctx.session.elicit_form(
+ message="Provide data",
+ requested_schema=schema,
+ related_request_id=ctx.request_id,
+ )
+ return response.action
+
+ async def handler(
+ message: str, response_type: Any, params: Any, context: Any
+ ) -> ElicitResult[dict[str, Any]]:
+ validated.append(TypeAdapter(response_type).validate_python(content))
+ return ElicitResult(action="accept", content={"name": "a"})
+
+ async with Client(server, mode="legacy", elicitation_handler=handler) as client:
+ result = await client.call_tool("ask", {})
+
+ assert result.data == "accept"
+ assert len(validated) == 1
+
+ @pytest.mark.parametrize("title", AWKWARD_TITLES.values(), ids=AWKWARD_TITLES)
+ async def test_elicitation_schema_with_any_title(self, title: str):
+ server = FastMCP("Forms")
+ validated: list[Any] = []
+
+ @server.tool
+ async def ask(ctx: Context) -> str:
+ response = await ctx.session.elicit_form(
+ message="Provide data",
+ requested_schema=nested_items_schema(title),
+ related_request_id=ctx.request_id,
+ )
+ return response.action
+
+ async def handler(
+ message: str, response_type: Any, params: Any, context: Any
+ ) -> ElicitResult[dict[str, Any]]:
+ validated.append(
+ TypeAdapter(response_type).validate_python(NESTED_ITEMS_VALUE)
+ )
+ return ElicitResult(action="accept", content={"name": "a"})
+
+ async with Client(server, mode="legacy", elicitation_handler=handler) as client:
+ result = await client.call_tool("ask", {})
+
+ assert result.data == "accept"
+ assert len(validated) == 1
+ child = validated[0].children[0]
+ assert isinstance(child, type(validated[0]))
+ assert child.name == "b"
+
+
+class TestPropertyNamesAreFields:
+ @pytest.mark.parametrize(
+ "name",
+ [
+ "__annotations__",
+ "__base__",
+ "__config__",
+ "__validators__",
+ "__slots__",
+ "_private",
+ "model_config",
+ "model_dump",
+ "model_fields",
+ "__class__",
+ "__dict__",
+ "__init__",
+ "__module__",
+ "__qualname__",
+ "__doc__",
+ "__eq__",
+ "model_post_init",
+ "model_validate",
+ "model_copy",
+ "_1",
+ ],
+ )
+ def test_reserved_names_become_aliased_fields(self, name: str):
+ generated = json_schema_to_type(
+ {
+ "type": "object",
+ "additionalProperties": True,
+ "properties": {
+ name: {"type": "string", "default": "default"},
+ "ordinary": {"type": "integer"},
+ },
+ "required": ["ordinary"],
+ }
+ )
+
+ assert issubclass(generated, BaseModel)
+ assert generated.model_config.get("extra") == "allow"
+ instance = generated.model_validate({name: "data", "ordinary": 3, "other": 1})
+ assert instance.model_dump(by_alias=True) == {
+ name: "data",
+ "ordinary": 3,
+ "other": 1,
+ }
+ defaulted = generated.model_validate({"ordinary": 3})
+ assert defaulted.model_dump(by_alias=True)[name] == "default"
+
+ @pytest.mark.parametrize("name", ["ordinary", "foo-bar", "json", "class"])
+ def test_other_names_keep_their_field_name(self, name: str):
+ generated = json_schema_to_type(
+ {
+ "type": "object",
+ "additionalProperties": True,
+ "properties": {name: {"type": "string"}},
+ }
+ )
+
+ assert issubclass(generated, BaseModel)
+ assert list(generated.model_fields) == [name]
+ assert generated.model_validate({name: "v"}).model_dump() == {name: "v"}
+
+ def test_renamed_field_does_not_collide_with_existing_property(self):
+ generated = json_schema_to_type(
+ {
+ "type": "object",
+ "additionalProperties": True,
+ "properties": {
+ "model_config": {"type": "string"},
+ "field_model_config": {"type": "integer"},
+ },
+ }
+ )
+
+ assert issubclass(generated, BaseModel)
+ instance = generated.model_validate(
+ {"model_config": "a", "field_model_config": 1}
+ )
+ assert instance.model_dump(by_alias=True) == {
+ "model_config": "a",
+ "field_model_config": 1,
+ }
+
+ def test_safe_create_model_keeps_field_metadata(self):
+ model = safe_create_model(
+ "Form",
+ {"__base__": (str, Field(description="Required input"))},
+ )
+
+ field_info = next(iter(model.model_fields.values()))
+ assert isinstance(field_info, FieldInfo)
+ assert field_info.alias == "__base__"
+ assert field_info.description == "Required input"
+ assert field_info.is_required()
+ with pytest.raises(ValidationError):
+ model.model_validate({})
+ assert model.model_validate({"__base__": "ok"}).model_dump(by_alias=True) == {
+ "__base__": "ok"
+ }
+
+
+DICTIONARY_DEFAULT = {"name": "text", "count": "int"}
+ANNOTATIONS_PROPERTY = {
+ "type": "object",
+ "title": "Result",
+ "additionalProperties": True,
+ "properties": {
+ "ok": {"type": "boolean"},
+ "__annotations__": {"default": DICTIONARY_DEFAULT},
+ },
+}
+ANNOTATIONS_CONTENTS = {
+ "default_applied": {"ok": True},
+ "value_provided": {"ok": True, "__annotations__": {"name": "other"}},
+}
+ANNOTATIONS_EXPECTED = {
+ "default_applied": {"ok": True, "__annotations__": DICTIONARY_DEFAULT},
+ "value_provided": {"ok": True, "__annotations__": {"name": "other"}},
+}
+
+
+class TestDictionaryDefaults:
+ def test_dictionary_defaults_are_kept_as_field_data(self):
+ generated = json_schema_to_type(ANNOTATIONS_PROPERTY)
+
+ assert issubclass(generated, BaseModel)
+ instance = generated.model_validate({"ok": True})
+ assert instance.model_dump(by_alias=True) == {
+ "ok": True,
+ "__annotations__": DICTIONARY_DEFAULT,
+ }
+
+ def test_dictionary_defaults_leave_class_annotations_unchanged(self):
+ generated = json_schema_to_type(ANNOTATIONS_PROPERTY)
+
+ assert issubclass(generated, BaseModel)
+ assert set(generated.__annotations__) == set(generated.model_fields)
+ assert set(generated.__annotations__).isdisjoint(DICTIONARY_DEFAULT)
+
+ @pytest.mark.parametrize("case", ANNOTATIONS_CONTENTS)
+ async def test_dictionary_defaults_in_tool_results(self, case: str):
+ server = FastMCP("Remote")
+
+ @server.tool(output_schema=ANNOTATIONS_PROPERTY)
+ def lookup() -> ToolResult:
+ return ToolResult(structured_content=ANNOTATIONS_CONTENTS[case])
+
+ async with Client(server) as client:
+ result = await client.call_tool("lookup", {})
+
+ assert isinstance(result.data, BaseModel)
+ assert result.data.model_dump(by_alias=True) == ANNOTATIONS_EXPECTED[case]
+ assert set(type(result.data).__annotations__) == set(
+ type(result.data).model_fields
+ )
+
+ @pytest.mark.parametrize("case", ANNOTATIONS_CONTENTS)
+ async def test_dictionary_defaults_in_elicitation_schemas(self, case: str):
+ server = FastMCP("Forms")
+ validated: list[BaseModel] = []
+
+ @server.tool
+ async def ask(ctx: Context) -> str:
+ response = await ctx.session.elicit_form(
+ message="Provide data",
+ requested_schema=ANNOTATIONS_PROPERTY,
+ related_request_id=ctx.request_id,
+ )
+ return response.action
+
+ async def handler(
+ message: str, response_type: Any, params: Any, context: Any
+ ) -> ElicitResult[dict[str, Any]]:
+ validated.append(
+ TypeAdapter(response_type).validate_python(ANNOTATIONS_CONTENTS[case])
+ )
+ return ElicitResult(action="accept", content={"ok": True})
+
+ async with Client(server, mode="legacy", elicitation_handler=handler) as client:
+ result = await client.call_tool("ask", {})
+
+ assert result.data == "accept"
+ assert len(validated) == 1
+ assert validated[0].model_dump(by_alias=True) == ANNOTATIONS_EXPECTED[case]
+ assert set(type(validated[0]).__annotations__) == set(
+ type(validated[0]).model_fields
+ )
+
+
+def fanout_schema(depth: int, fanout: int) -> dict[str, Any]:
+ defs: dict[str, Any] = {"L0": {"type": "string"}}
+ for i in range(1, depth + 1):
+ defs[f"L{i}"] = {"anyOf": [{"$ref": f"#/$defs/L{i - 1}"}] * fanout}
+ return {
+ "type": "object",
+ "title": "SharedGraph",
+ "properties": {"x": {"$ref": f"#/$defs/L{depth}"}},
+ "$defs": defs,
+ }
+
+
+def flat_chain_schema(length: int) -> dict[str, Any]:
+ defs: dict[str, Any] = {
+ f"L{i}": {"$ref": f"#/$defs/L{i + 1}"} for i in range(length)
+ }
+ defs[f"L{length}"] = {"type": "string"}
+ return {
+ "type": "object",
+ "title": "FlatChain",
+ "properties": {"x": {"$ref": "#/$defs/L0"}},
+ "$defs": defs,
+ }
+
+
+def wrapped_definition_schema(
+ title: str, *, additional_properties: bool, description_size: int = 3_000
+) -> dict[str, Any]:
+ wrapper: dict[str, Any] = {
+ "type": "object",
+ "title": "Wrapper",
+ "properties": {"child": {"$ref": "#/$defs/Large"}},
+ "required": ["child"],
+ }
+ if additional_properties:
+ wrapper["additionalProperties"] = True
+ return {
+ "type": "object",
+ "title": title,
+ "properties": {"wrapper": wrapper},
+ "required": ["wrapper"],
+ "$defs": {
+ "Large": {
+ "type": "object",
+ "title": "Large",
+ "description": "x" * description_size,
+ "properties": {"x": {"type": "string"}},
+ }
+ },
+ }
+
+
+class TestConversionLimits:
+ def test_shared_references_are_converted_once(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ calls = 0
+ original = json_schema_type._resolve_ref
+
+ def counting_resolve(ref: str, schemas: Any) -> Any:
+ nonlocal calls
+ calls += 1
+ return original(ref, schemas)
+
+ monkeypatch.setattr(json_schema_type, "_resolve_ref", counting_resolve)
+ generated = json_schema_to_type(fanout_schema(depth=8, fanout=3))
+
+ assert TypeAdapter(generated).validate_python({"x": "ok"}).x == "ok" # ty: ignore[unresolved-attribute]
+ assert calls <= 9
+
+ def test_long_reference_chain_is_rejected(self):
+ with pytest.raises(ValueError, match="too deeply nested"):
+ json_schema_to_type(flat_chain_schema(400))
+
+ def test_repeated_type_lists_are_rejected(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(
+ json_schema_type, "_MAX_CONVERSION_STEPS", 200, raising=False
+ )
+ schema: dict[str, Any] = {"type": "string"}
+ for _ in range(8):
+ schema = {"type": ["array", "array"], "items": schema}
+
+ with pytest.raises(ValueError, match="too large"):
+ json_schema_to_type(schema)
+
+ def test_deeply_nested_models_still_convert(self):
+ depth = 20
+ defs: dict[str, Any] = {
+ f"M{i}": {
+ "type": "object",
+ "properties": {
+ "child": {
+ "anyOf": [{"$ref": f"#/$defs/M{i + 1}"}, {"type": "null"}]
+ }
+ },
+ }
+ for i in range(depth)
+ }
+ defs[f"M{depth}"] = {
+ "type": "object",
+ "properties": {"leaf": {"type": "string"}},
+ }
+ schema = {
+ "type": "object",
+ "title": "Deep",
+ "properties": {"child": {"$ref": "#/$defs/M0"}},
+ "$defs": defs,
+ }
+ value: dict[str, Any] = {"leaf": "ok"}
+ for _ in range(depth):
+ value = {"child": value}
+
+ instance = TypeAdapter(json_schema_to_type(schema)).validate_python(
+ {"child": value}
+ )
+
+ node: Any = instance.child # ty: ignore[unresolved-attribute]
+ for _ in range(depth):
+ node = node.child
+ assert node.leaf == "ok"
+
+
+class TestClassCache:
+ def test_failed_conversion_can_be_retried(self):
+ schema = {"type": "object", "title": "RetryInvalid", "properties": {"x": 123}}
+
+ for _ in range(2):
+ with pytest.raises(AttributeError):
+ json_schema_to_type(schema)
+
+ def test_rejected_conversion_leaves_cache_unchanged(self):
+ before = len(json_schema_type._classes)
+
+ with pytest.raises(ValueError):
+ json_schema_to_type(flat_chain_schema(400))
+
+ assert len(json_schema_type._classes) == before
+
+ def test_cache_is_bounded(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(json_schema_type._classes, "max_entries", 3)
+ json_schema_type._classes.clear()
+
+ for i in range(5):
+ json_schema_to_type(
+ {
+ "type": "object",
+ "title": f"Unique{i}",
+ "properties": {"x": {"type": "string"}},
+ }
+ )
+
+ assert len(json_schema_type._classes) == 3
+
+ def test_size_budget_evicts_large_schemas(self, monkeypatch: pytest.MonkeyPatch):
+ def schema(i: int) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "title": f"Large{i}",
+ "description": "x" * 1000,
+ "properties": {"x": {"type": "string"}},
+ }
+
+ weight = len(json.dumps(schema(0), sort_keys=True))
+ monkeypatch.setattr(json_schema_type._classes, "max_weight", weight * 3 // 2)
+ json_schema_type._classes.clear()
+
+ json_schema_to_type(schema(0))
+ json_schema_to_type(schema(1))
+
+ assert len(json_schema_type._classes) == 1
+
+ def test_schema_over_size_budget_is_not_cached(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ monkeypatch.setattr(json_schema_type._classes, "max_weight", 10)
+ json_schema_type._classes.clear()
+
+ json_schema_to_type(
+ {"type": "object", "title": "Big", "properties": {"x": {"type": "string"}}}
+ )
+
+ assert len(json_schema_type._classes) == 0
+
+ def test_evicted_classes_are_released(self, monkeypatch: pytest.MonkeyPatch):
+ monkeypatch.setattr(json_schema_type._classes, "max_entries", 2)
+ monkeypatch.setattr(json_schema_type._adapters, "max_entries", 2)
+ json_schema_type._classes.clear()
+ json_schema_type._adapters.clear()
+ refs: list[weakref.ref[type]] = []
+
+ for i in range(4):
+ schema = {
+ "type": "object",
+ "title": f"Released{i}",
+ "properties": {"x": {"type": "string"}},
+ }
+ value = json_schema_to_type_adapter(schema).validate_python({"x": "a"})
+ refs.append(weakref.ref(type(value)))
+ del value
+ gc.collect()
+
+ assert [ref() is not None for ref in refs] == [False, False, True, True]
+
+ def test_nested_classes_depend_on_root_definitions(self):
+ def schema(value_type: str) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "nested": {
+ "type": "object",
+ "properties": {"value": {"$ref": "#/$defs/Value"}},
+ }
+ },
+ "$defs": {"Value": {"type": value_type}},
+ }
+
+ as_string = TypeAdapter(json_schema_to_type(schema("string")))
+ as_integer = TypeAdapter(json_schema_to_type(schema("integer")))
+
+ string_value = as_string.validate_python({"nested": {"value": "a"}})
+ integer_value = as_integer.validate_python({"nested": {"value": 3}})
+ assert string_value.nested.value == "a" # ty: ignore[unresolved-attribute]
+ assert integer_value.nested.value == 3 # ty: ignore[unresolved-attribute]
+
+ def test_classes_from_one_conversion_are_charged_for_its_root_schema(
+ self, monkeypatch: pytest.MonkeyPatch
+ ):
+ schema = wrapped_definition_schema("Charged", additional_properties=True)
+ root_size = len(json.dumps(schema, sort_keys=True))
+ monkeypatch.setattr(json_schema_type._classes, "max_weight", root_size * 3 // 2)
+ json_schema_type._classes.clear()
+
+ json_schema_to_type(schema)
+
+ assert len(json_schema_type._classes) == 1
+
+ @pytest.mark.parametrize("additional_properties", [False, True])
+ def test_classes_referencing_a_large_definition_are_charged_for_it(
+ self, monkeypatch: pytest.MonkeyPatch, additional_properties: bool
+ ):
+ monkeypatch.setattr(json_schema_type._classes, "max_weight", 2_000)
+ monkeypatch.setattr(json_schema_type._adapters, "max_weight", 2_000)
+ json_schema_type._classes.clear()
+ json_schema_type._adapters.clear()
+ large_classes: list[weakref.ref[type]] = []
+
+ for i in range(4):
+ schema = wrapped_definition_schema(
+ f"Referencing{i}", additional_properties=additional_properties
+ )
+ value = json_schema_to_type_adapter(schema).validate_python(
+ {"wrapper": {"child": {"x": "a"}}}
+ )
+ large_classes.append(weakref.ref(type(value.wrapper.child)))
+ del value
+ gc.collect()
+
+ assert [ref() for ref in large_classes] == [None] * 4
+ assert len(json_schema_type._classes) == 0
+ assert len(json_schema_type._adapters) == 0