json_schema_to_type crashes on Python keywords, boolean schemas, empty enums, and name collisions

[strawgate]

Description

json_schema_to_type() in src/fastmcp/utilities/json_schema_type.py crashes on several valid JSON Schema inputs that commonly appear in OpenAPI-generated tool output schemas:

1. Python keyword property names (class, return, import) — TypeError: Field names must not be keywords
2. Boolean schemas (True / False) — AttributeError: 'bool' object has no attribute 'get'
3. Empty enum ({"enum": []}) — AssertionError: literal "expected" cannot be empty
4. Sanitized name collisions (foo-bar + foo_bar both become foo_bar) — TypeError: Field name duplicated
5. Empty/whitespace property names ("", " ") — same duplicate field crash

These all cause the client to crash when parsing structured tool output from servers that use these schema patterns.

Reproduction

from fastmcp.utilities.json_schema_type import json_schema_to_type

# 1. Python keywords
json_schema_to_type({"type": "object", "properties": {"class": {"type": "string"}}})
# TypeError: Field names must not be keywords: 'class'

# 2. Boolean schema
json_schema_to_type(True)
# AttributeError: 'bool' object has no attribute 'get'

# 3. Empty enum
from pydantic import TypeAdapter
T = json_schema_to_type({"type": "object", "properties": {"x": {"enum": []}}})
TypeAdapter(T)  # AssertionError

# 4. Name collision
json_schema_to_type({"type": "object", "properties": {"foo-bar": {"type": "string"}, "foo_bar": {"type": "string"}}})
# TypeError: Field name duplicated: 'foo_bar'

Expected behavior

All of these should produce usable Python types without crashing.

[marvin-context-protocol]

Claude finished @strawgate's task in 4m 28s —— View job

---

Triage: json_schema_to_type crash bugs

All five crashes are confirmed and reproducible. PR #3818 already addresses all of them. The bugs are isolated to _create_dataclass (the _create_pydantic_model path is unaffected for keywords and collisions).

• Gather context and read source code
• Verify all reported crashes
• Analyze root causes and identify fixes
• Search for related issues/PRs
• Provide detailed action plan

Recommendation

PR #3818 (fix/json-schema-to-type-crashes) already implements fixes for all five issues. It is marked [DNM] but the approach is correct — the diff is clean and minimal. A maintainer should review that PR.

Findings

All five crashes are real and affect the _create_dataclass code path (objects without additionalProperties: true). The _create_pydantic_model path is already resilient because it uses raw property names as dict keys instead of make_dataclass.

Bug 1 — Python keyword field names (json_schema_type.py:565,602): _sanitize_name() converts special chars to underscores but doesn't check for Python keywords. make_dataclass() rejects keyword field names like class, return, import.

Bug 2 — Boolean schemas at top-level (json_schema_type.py:180): json_schema_to_type() calls schema.get("type") immediately, which crashes on bool input. The internal _schema_to_type() already handles booleans (lines 333-336), but the public entry point doesn't.

Bug 3 — Empty enum (json_schema_type.py:267-269): _create_enum() produces Literal[()] for empty value lists, which crashes Pydantic's TypeAdapter with AssertionError: literal "expected" cannot be empty.

Bug 4+5 — Name collisions (json_schema_type.py:565,602): Multiple JSON properties that sanitize to the same Python identifier (e.g., foo-bar + foo_bar → foo_bar, or "" + " " → field_) cause make_dataclass to fail with duplicate field names.

Verification

Confirmed all five crashes:

1. Python keywords: CRASH - TypeError: Field names must not be keywords: 'class'
2. Boolean schema True: CRASH - AttributeError: 'bool' object has no attribute 'get'
2b. Boolean schema False: CRASH - AttributeError: 'bool' object has no attribute 'get'
3. Empty enum: CRASH - AssertionError: literal "expected" cannot be empty, obj=typing.Literal[()]
4. Name collision: CRASH - TypeError: Field name duplicated: 'foo_bar'
5. Empty/whitespace names: CRASH - TypeError: Field name duplicated: 'field'

Also confirmed the _create_pydantic_model path (triggered when additionalProperties: true) does not crash for keywords or collisions, since it uses raw property names as annotation dict keys.

Detailed Action Plan

All changes in src/fastmcp/utilities/json_schema_type.py:

1. Boolean schemas — json_schema_to_type() (line ~180)
Add early returns before any .get() call:

if schema is True:
    return Any
if schema is False:
    return _UnsatisfiableType

Update the type signature to accept Mapping[str, Any] | bool.

2. Python keywords — _sanitize_name() (line ~433)
After the existing sanitization steps, add:

import keyword
if keyword.iskeyword(cleaned):
    cleaned = f"{cleaned}_"

This follows PEP 8 convention. The alias metadata in field(metadata={"alias": prop_name}) already preserves the original JSON name for round-tripping.

3. Empty enum — _create_enum() (line ~267)
Add early return:

if not values:
    return Any

4+5. Name collisions — _create_dataclass() (line ~564)
Track used names and deduplicate:

used_field_names: set[str] = set()
for prop_name, prop_schema in properties.items():
    field_name = _sanitize_name(prop_name)
    base = field_name
    counter = 2
    while field_name in used_field_names:
        field_name = f"{base}_{counter}"
        counter += 1
    used_field_names.add(field_name)

Tests — Add a TestCrashPrevention class in tests/utilities/json_schema_type/test_json_schema_type.py covering all five cases, verifying both no-crash and correct round-tripping via TypeAdapter.

Related Issues and Pull Requests

Repository	Issue or PR	Relevance
PrefectHQ/fastmcp	#3818 — Fix json_schema_to_type crashes	PR already implementing fixes for all five bugs reported here (marked [DNM])
PrefectHQ/fastmcp	#3783 — Boolean true/false property schema	Prior issue for boolean schemas as properties (fixed in #3785). This issue covers the remaining case: boolean schemas at the top level.
PrefectHQ/fastmcp	#3785 — Fix boolean property schemas	Merged PR that fixed boolean schemas in properties but didn't handle top-level boolean schemas.
PrefectHQ/fastmcp	#1603 — json_schema_to_type ignores AdditionalProperties in nested definitions	Related json_schema_to_type issue (separate bug)

Related Files

File	Relevance	Sections
src/fastmcp/utilities/json_schema_type.py	Contains all five bugs	L121-202 (entry point), L266-269 (enum), L418-433 (sanitize), L529-602 (dataclass)
src/fastmcp/client/mixins/tools.py	Caller — crashes propagate from here when parsing tool output	L428
tests/utilities/json_schema_type/test_json_schema_type.py	Existing tests — need crash prevention tests added

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

[marvin-context-protocol]

Found 1 possible duplicate issue:

1. JSON schema parsing does not handle boolean true/false as a property schema  #3783: JSON schema parsing does not handle boolean true/false as a property schema

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment