mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-09 07:09:11 +02:00
111 lines
4.4 KiB
Text
111 lines
4.4 KiB
Text
---
|
|
title: json_schema
|
|
sidebarTitle: json_schema
|
|
---
|
|
|
|
# `fastmcp.utilities.json_schema`
|
|
|
|
## Functions
|
|
|
|
### `replace_refs` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L7" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>
|
|
|
|
```python
|
|
replace_refs(*args: Any, **kwargs: Any) -> Any
|
|
```
|
|
|
|
|
|
Call jsonref lazily while preserving the module's patchable boundary.
|
|
|
|
|
|
### `require_discriminator_property` <sup><a href="https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/json_schema.py#L154" 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#L185" 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#L336" 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#L750" 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.
|
|
|