> ## Documentation Index > Fetch the complete documentation index at: https://gofastmcp.com/llms.txt > Use this file to discover all available pages before exploring further. # json_schema # `fastmcp.utilities.json_schema` ## Functions ### `replace_refs` ```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} replace_refs(*args: Any, **kwargs: Any) -> Any ``` Call jsonref lazily while preserving the module's patchable boundary. ### `require_discriminator_property` ```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} 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` ```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} 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 circular schemas, and for schemas whose inlined form would be very large or deeply nested, 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` ```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} 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` ```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}} 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.