Implementation:BerriAI Litellm Dot Notation Indexing

Attribute	Value
Sources	litellm/litellm_core_utils/dot_notation_indexing.py
Domains	Data Access, Dictionary Utilities, JSONPath
Last Updated	2026-02-15 16:00 GMT

Overview

Provides path-based navigation utilities for reading and deleting values in nested dictionaries using dot notation and JSONPath-like array syntax.

Description

This module implements a zero-dependency custom path parser for nested dictionary operations. It supports two primary operations:

• get_nested_value -- Retrieves a value from a nested dictionary using dot-separated key paths. Supports escaped dots (\.) for keys that contain literal dots (e.g., Kubernetes-style annotations). Automatically strips a metadata. prefix if present.
• delete_nested_value -- Deletes a field from a nested dictionary using JSONPath-like notation, including array wildcards ([*]) and specific array indices ([0]). Creates a deep copy before modification, leaving the original data intact.

Internal helpers include _parse_path_segments for tokenizing paths and _delete_nested_value_custom for recursive in-place deletion. The is_nested_path utility checks whether a path string requires nested handling.

Used by JWT Auth for extracting user roles from tokens and by additional_drop_params for removing nested fields from request parameters.

Usage

Import get_nested_value when you need to safely read deeply nested dictionary values with a string path. Import delete_nested_value when you need to remove fields from nested structures (including arrays) without mutating the original.

Code Reference

Source Location

litellm/litellm_core_utils/dot_notation_indexing.py (245 lines)

Signature

def get_nested_value(
    data: Dict[str, Any], key_path: str, default: Optional[T] = None
) -> Optional[T]

def delete_nested_value(
    data: Dict[str, Any],
    path: str,
    depth: int = 0,
    max_depth: int = 20,
) -> Dict[str, Any]

def is_nested_path(path: str) -> bool

# Internal helpers
def _parse_path_segments(path: str) -> list
def _delete_nested_value_custom(
    data: Union[Dict[str, Any], List[Any]],
    segments: list,
    segment_index: int = 0,
) -> None

Import

from litellm.litellm_core_utils.dot_notation_indexing import (
    get_nested_value,
    delete_nested_value,
    is_nested_path,
)

I/O Contract

get_nested_value

Direction	Name	Type	Description
Input	data	Dict[str, Any]	Dictionary to search
Input	key_path	str	Dot-notation path (e.g., "a.b.c")
Input	default	Optional[T]	Default value if path not found (default: None)
Output	return	Optional[T]	Value at path, or the default

delete_nested_value

Direction	Name	Type	Description
Input	data	Dict[str, Any]	Dictionary to modify (deep-copied internally)
Input	path	str	JSONPath-like path to the field to remove
Input	depth	int	Current recursion depth (default: 0, kept for API compatibility)
Input	max_depth	int	Maximum recursion depth (default: 20)
Output	return	Dict[str, Any]	New dictionary with the field removed

is_nested_path

Direction	Name	Type	Description
Input	path	str	Path string to check
Output	return	bool	True if path contains . or [

Usage Examples

from litellm.litellm_core_utils.dot_notation_indexing import (
    get_nested_value,
    delete_nested_value,
    is_nested_path,
)

# Read a nested value
data = {"a": {"b": {"c": "value"}}}
result = get_nested_value(data, "a.b.c")
# result == "value"

# Read with default
result = get_nested_value(data, "a.b.missing", "fallback")
# result == "fallback"

# Handle keys with dots (escaped)
data = {"kubernetes.io": {"namespace": "default"}}
result = get_nested_value(data, "kubernetes\\.io.namespace")
# result == "default"

# Delete a field inside array elements
data = {"tools": [{"name": "t1", "input_examples": ["ex"]}, {"name": "t2", "input_examples": ["ex2"]}]}
cleaned = delete_nested_value(data, "tools[*].input_examples")
# cleaned == {"tools": [{"name": "t1"}, {"name": "t2"}]}

# Check if a path is nested
is_nested_path("simple")       # False
is_nested_path("a.b.c")       # True
is_nested_path("arr[0].field") # True

Related Pages

• BerriAI_Litellm_JSON_Validation_Rule -- validates JSON schemas; complementary to path-based data access
• BerriAI_Litellm_Safe_JSON_Dumps -- safe serialization used alongside nested data structures