dereference_refs#

langchain_core.utils.json_schema.dereference_refs(
schema_obj: dict,
*,
full_schema: dict | None = None,
skip_keys: Sequence[str] | None = None,
) → dict[source]#

Resolve and inline JSON Schema $ref references in a schema object.

This function processes a JSON Schema and resolves all $ref references by replacing them with the actual referenced content. It handles both simple references and complex cases like circular references and mixed $ref objects that contain additional properties alongside the $ref.

Parameters:

  • schema_obj (dict) – The JSON Schema object or fragment to process. This can be a complete schema or just a portion of one.

  • full_schema (Optional[dict]) – The complete schema containing all definitions that $refs might point to. If not provided, defaults to schema_obj (useful when the schema is self-contained).

  • skip_keys (Optional[Sequence[str]]) –

    Controls recursion behavior and reference resolution depth: - If None (default): Only recurse under ‘$defs’ and use shallow reference

    resolution (break cycles but don’t deep-inline nested refs)

    • If provided (even as []): Recurse under all keys and use deep reference resolution (fully inline all nested references)

Returns:

A new dictionary with all $ref references resolved and inlined. The original schema_obj is not modified.

Return type:

dict

Examples

Basic reference resolution: >>> schema = { … “type”: “object”, … “properties”: {“name”: {“$ref”: “#/$defs/string_type”}}, … “$defs”: {“string_type”: {“type”: “string”}}, … } >>> result = dereference_refs(schema) >>> result[“properties”][“name”] # {“type”: “string”}

Mixed $ref with additional properties: >>> schema = { … “properties”: { … “name”: {“$ref”: “#/$defs/base”, “description”: “User name”} … }, … “$defs”: {“base”: {“type”: “string”, “minLength”: 1}}, … } >>> result = dereference_refs(schema) >>> result[“properties”][“name”] # {“type”: “string”, “minLength”: 1, “description”: “User name”}

Handling circular references: >>> schema = { … “properties”: {“user”: {“$ref”: “#/$defs/User”}}, … “$defs”: { … “User”: { … “type”: “object”, … “properties”: {“friend”: {“$ref”: “#/$defs/User”}}, … } … }, … } >>> result = dereference_refs(schema) # Won’t cause infinite recursion

Note

  • Circular references are handled gracefully by breaking cycles

  • Mixed $ref objects (with both $ref and other properties) are supported

  • Additional properties in mixed $refs override resolved properties

  • The $defs section is preserved in the output by default

On this page