chore: import upstream snapshot with attribution

2026-07-13 12:39:59 +08:00
commit 60e0ffc959
1282 changed files with 294901 additions and 0 deletions
@@ -0,0 +1,101 @@
+---
+title: json_schema
+sidebarTitle: json_schema
+---
+
+# `fastmcp.utilities.json_schema`
+
+## Functions
+
+### `require_discriminator_property` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L116" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+require_discriminator_property(schema: dict[str, Any]) -> dict[str, Any]
+```
+
+
+Keep an OpenAPI discriminator's tag mandatory after the keyword is dropped.
+
+Returns a copy of *schema* with ``discriminator.propertyName`` added to each
+``anyOf``/``oneOf`` variant's ``required`` list. A Pydantic discriminated
+union whose tag has a default omits that tag from ``required``; without this,
+an untagged payload passes the generated schema but fails later in the source
+model with ``union_tag_not_found``. No-op if there is no string
+``propertyName``.
+
+
+### `dereference_refs` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L147" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+dereference_refs(schema: dict[str, Any]) -> dict[str, Any]
+```
+
+
+Resolve all $ref references in a JSON schema by inlining definitions.
+
+This function resolves $ref references that point to $defs, replacing them
+with the actual definition content while preserving sibling keywords (like
+description, default, examples) that Pydantic places alongside $ref.
+
+This is necessary because some MCP clients (e.g., VS Code Copilot) don't
+properly handle $ref in tool input schemas.
+
+For self-referencing/circular schemas where full dereferencing is not possible,
+this function falls back to resolving only the root-level $ref while preserving
+$defs for nested references.
+
+Only local ``$ref`` values (those starting with ``#``) are resolved.
+Remote URIs (``http://``, ``file://``, etc.) are stripped before
+resolution to prevent SSRF / local-file-inclusion attacks when proxying
+schemas from untrusted servers.
+
+**Args:**
+- `schema`: JSON schema dict that may contain $ref references
+
+**Returns:**
+- A new schema dict with $ref resolved where possible and $defs removed
+- when no longer needed
+
+
+### `resolve_root_ref` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L294" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+resolve_root_ref(schema: dict[str, Any]) -> dict[str, Any]
+```
+
+
+Resolve $ref at root level to meet MCP spec requirements.
+
+MCP specification requires outputSchema to have "type": "object" at the root level.
+When Pydantic generates schemas for self-referential models, it uses $ref at the
+root level pointing to $defs. This function resolves such references by inlining
+the referenced definition while preserving $defs for nested references.
+
+**Args:**
+- `schema`: JSON schema dict that may have $ref at root level
+
+**Returns:**
+- A new schema dict with root-level $ref resolved, or the original schema
+- if no resolution is needed
+
+
+### `compress_schema` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L688" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
+
+```python
+compress_schema(schema: dict[str, Any], prune_params: list[str] | None = None, prune_additional_properties: bool = False, prune_titles: bool = False, dereference: bool = False) -> dict[str, Any]
+```
+
+
+Compress and optimize a JSON schema for MCP compatibility.
+
+**Args:**
+- `schema`: The schema to compress
+- `prune_params`: List of parameter names to remove from properties
+- `prune_additional_properties`: Whether to remove additionalProperties\: false.
+Defaults to False to maintain MCP client compatibility, as some clients
+(e.g., Claude) require additionalProperties\: false for strict validation.
+- `prune_titles`: Whether to remove title fields from the schema
+- `dereference`: Whether to dereference $ref by inlining definitions.
+Defaults to False; dereferencing is typically handled by
+middleware at serve-time instead.
+