Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions by strawgate · Pull Request #3818 · PrefectHQ/fastmcp

strawgate · 2026-04-10T16:28:23Z

Summary

json_schema_to_type() crashes on several valid JSON Schema inputs that appear in real-world OpenAPI specs. This PR fixes five crash paths without changing any public API.

Python keyword property names (class, return, from, in, etc.) crashed make_dataclass. Now appends a trailing underscore per PEP 8 convention (class_), with the original name preserved in field alias metadata for JSON round-tripping. This is the dominant crash pattern — 388 out of 388 TypeErrors (100%) across 232K real-world schemas from APIs.guru are keyword crashes. from alone accounts for 232 of them (common in AWS API pagination/date-range schemas).

Boolean schemas at the public entry point — #3785 fixed _schema_to_type (internal) for boolean property schemas, but calling json_schema_to_type(True) directly still crashes since the public function's type hint is Mapping[str, Any]. This PR widens the signature to Mapping[str, Any] | bool and adds the same handling at the entry point. Related: #3783.

Empty enum values ({"enum": []}) produced Literal[()] which crashes Pydantic's schema generator. Now returns the unsatisfiable type (matching JSON Schema 2020-12 semantics: empty enum = no value is valid).

Name collisions after sanitization (foo-bar and foo_bar both become foo_bar) crashed make_dataclass with a duplicate field error. Now appends a numeric suffix (foo_bar_2).

All changes are crash→works. No existing working behavior is modified.

# All of these previously crashed, now work:
json_schema_to_type(True)                    # → Any
json_schema_to_type(False)                   # → unsatisfiable type
json_schema_to_type({"type": "object", "properties": {"class": {"type": "string"}}})
json_schema_to_type({"type": "object", "properties": {"foo-bar": {}, "foo_bar": {}}})

Impact on real-world schemas

Tested against 232K schemas from 4,120 OpenAPI specs (APIs.guru directory):

	Before	After
TypeErrors	388	~2
SchemaErrors	277	277
Total crash rate	0.29%	~0.12%

Closes #3817

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4058bc6359

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-10T16:31:20Z

+    if not values:
+        # Empty enum means no valid value; fall back to Any to avoid
+        # Pydantic's AssertionError on ``Literal[()]``.
+        return Any


Keep empty enum unsatisfiable instead of widening to Any

Returning Any for {"enum": []} silently inverts JSON Schema semantics: an empty enum means no value is valid, but this branch now accepts every input and can let invalid payloads pass validation in production. This is especially risky because callers will not see an error anymore and may assume schema constraints are being enforced; using the existing unsatisfiable type (like the false schema path) would avoid the crash without dropping the constraint.

Useful? React with 👍 / 👎.

marvin-context-protocol · 2026-04-10T21:00:30Z

Test Failure Analysis

Summary: The static analysis (prek) CI check failed because tests/utilities/json_schema_type/test_real_world_schemas.py has import ordering and formatting issues that were not fixed before pushing.

Root Cause: ruff check found 4 import-ordering violations and ruff format found 1 formatting issue in the new test file. Specifically, from pydantic import TypeAdapter was placed after the from fastmcp... import instead of before it (isort requires third-party imports before first-party imports). The prek run --all-files pre-commit hook was not run before committing.

Suggested Solution: Run the following locally, then commit and push the resulting changes:

uv run prek run --all-files

This will auto-fix the import ordering and formatting issues. The change is minor — from pydantic import TypeAdapter just needs to move above from fastmcp.utilities.json_schema_type import json_schema_to_type.

Detailed Analysis

Failed checks:

ruff check: Found 4 errors (4 fixed) — exit code 1 because files were modified
ruff format: 1 file reformatted

Diff applied by ruff (from CI log):

--- a/tests/utilities/json_schema_type/test_real_world_schemas.py
+++ b/tests/utilities/json_schema_type/test_real_world_schemas.py
@@ -19,9 +19,9 @@
 from pathlib import Path

 import pytest
 import yaml
+from pydantic import TypeAdapter

 from fastmcp.utilities.json_schema_type import json_schema_to_type
-from pydantic import TypeAdapter

Not blocking (yet): The loq file-size check reported 11 violations but explicitly stated "loq violations not enforced... yet!" — this does not block the PR.

Related Files

tests/utilities/json_schema_type/test_real_world_schemas.py — the new test file with import ordering/formatting issues

jlowin

Fixes look correct across all five crash paths. Lint fixup pushed — good to go.

- Handle boolean schemas (True/False) at the public entry point - Append trailing underscore to Python keyword property names (PEP 8) - Return Any for empty enum values instead of crashing Pydantic - Deduplicate field names after sanitization to prevent collisions (e.g. "foo-bar" and "foo_bar" both sanitizing to "foo_bar") 🤖 Generated with Claude Code Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 43d09d28ab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-04-11T15:35:44Z

+    if schema is True:
+        return Any
+    if schema is False:
+        return _UnsatisfiableType  # type: ignore[return-value]  # ty:ignore[invalid-return-type]


Enforce name validation for top-level boolean schemas

The new boolean fast-path returns immediately for schema is True/False, which bypasses the existing non-object name validation. As a result, json_schema_to_type(True, name="X") and json_schema_to_type(False, name="X") now succeed while other non-object schemas still raise ValueError, violating the documented contract that name is only for object schemas. In callers that always pass a name, this can silently turn a schema mismatch into Any (or an unsatisfiable type) instead of surfacing the error.

Useful? React with 👍 / 👎.

strawgate changed the title ~~Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions~~ [DNM] Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions Apr 10, 2026

marvin-context-protocol Bot added bug Something isn't working. Reports of errors, unexpected behavior, or broken functionality. openapi Related to OpenAPI integration, parsing, or code generation features. labels Apr 10, 2026

chatgpt-codex-connector Bot reviewed Apr 10, 2026

View reviewed changes

marvin-context-protocol Bot mentioned this pull request Apr 10, 2026

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

Closed

strawgate force-pushed the fix/json-schema-to-type-crashes branch 2 times, most recently from 9b372eb to d644946 Compare April 10, 2026 16:34

strawgate force-pushed the fix/json-schema-to-type-crashes branch from 60a66b0 to d644946 Compare April 10, 2026 21:04

strawgate changed the title ~~[DNM] Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions~~ Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions Apr 11, 2026

jlowin approved these changes Apr 11, 2026

View reviewed changes

strawgate and others added 2 commits April 11, 2026 11:29

Move local imports to module level in test_json_schema_type

43d09d2

jlowin force-pushed the fix/json-schema-to-type-crashes branch from 59067fc to 43d09d2 Compare April 11, 2026 15:29

jlowin merged commit 4b59e0d into main Apr 11, 2026
9 checks passed

jlowin deleted the fix/json-schema-to-type-crashes branch April 11, 2026 15:29

chatgpt-codex-connector Bot reviewed Apr 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions#3818

Fix json_schema_to_type crashes on keywords, boolean schemas, empty enums, and name collisions#3818
jlowin merged 2 commits intomainfrom
fix/json-schema-to-type-crashes

strawgate commented Apr 10, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 10, 2026

Uh oh!

marvin-context-protocol Bot commented Apr 10, 2026

Uh oh!

jlowin left a comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Apr 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

strawgate commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Impact on real-world schemas

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

marvin-context-protocol Bot commented Apr 10, 2026

Test Failure Analysis

Uh oh!

jlowin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Apr 11, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

strawgate commented Apr 10, 2026 •

edited

Loading