dereference_refs() — langchain Function Reference

Architecture documentation for the dereference_refs() function in json_schema.py from the langchain codebase.

Function python CoreAbstractions MessageSchema calls 1

Entity Profile

CoreAbstractions→ MessageSchema→ dereference_refs() — langchain Function Reference

Dependency Diagram

graph TD
  3bd82155_d14b_b918_3a21_94904c5fbe2b["dereference_refs()"]
  e949a363_87d5_a34f_ea76_18a6a6268498["json_schema.py"]
  3bd82155_d14b_b918_3a21_94904c5fbe2b -->|defined in| e949a363_87d5_a34f_ea76_18a6a6268498
  f0fb6db9_b0d7_49d4_8b5e_33f7376daf2a["_dereference_refs_helper()"]
  3bd82155_d14b_b918_3a21_94904c5fbe2b -->|calls| f0fb6db9_b0d7_49d4_8b5e_33f7376daf2a
  style 3bd82155_d14b_b918_3a21_94904c5fbe2b fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

libs/core/langchain_core/utils/json_schema.py lines 188–273

def dereference_refs(
    schema_obj: dict,
    *,
    full_schema: dict | None = None,
    skip_keys: Sequence[str] | None = None,
) -> dict:
    """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.

    Handles both simple references and complex cases like circular references and mixed
    `$ref` objects that contain additional properties alongside the `$ref`.

    Args:
        schema_obj: The JSON Schema object or fragment to process.

            This can be a complete schema or just a portion of one.
        full_schema: 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: 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.

    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
    """
    full = full_schema or schema_obj
    keys_to_skip = list(skip_keys) if skip_keys is not None else ["$defs"]
    shallow = skip_keys is None
    return cast(