Overview
The Schema Parser module provides utilities for reading and writing values by JSON Path within data structures, and for extracting all possible JSON Paths from a JSON Schema definition.
Description
This module contains three groups of functionality:
JSON Path Read/Write: The get_value_from_path function traverses a dictionary, list, or string using a dot-separated JSON Path (e.g., $.person.name) to retrieve a nested value. The write_value_to_path function recursively writes a value to a nested location specified by a JSON Path, creating intermediate dictionaries or lists as needed. The fill_list helper ensures arrays are padded with None values to accommodate index-based writes.
Schema Path Extraction: The get_all_paths function takes a JSON Schema and returns a set of all possible JSON Paths within that schema. It dereferences $ref pointers using jsonref, then recursively walks the schema handling properties, additionalProperties, items (arrays), conditional subschemas (if/then/else), and composition keywords (oneOf, anyOf, allOf). Wildcard paths (.*) are generated for schemas that allow arbitrary object properties.
Usage
Use this module when you need to navigate or manipulate data structures using JSON Path notation, or when you need to determine all valid paths within a JSON Schema. It is used internally by the Guardrails validation pipeline to access specific fields for per-property validation and to construct error paths.
Code Reference
Source Location
- Repository: Guardrails
- File:
guardrails/schema/parser.py
Signature
def get_value_from_path(
object: Optional[Union[str, List[Any], Dict[Any, Any]]],
property_path: str,
) -> Any
def fill_list(desired_length: int, array: list) -> list
def write_value_to_path(
write_object: Union[str, List[Any], Dict[Any, Any]],
property_path: str,
value: Any,
) -> Any
def get_all_paths(
json_schema: Dict[str, Any],
*,
paths: Optional[Set[str]] = None,
json_path: str = "$",
) -> Set[str]
Import
from guardrails.schema.parser import get_value_from_path, write_value_to_path
from guardrails.schema.parser import get_all_paths
from guardrails.schema.parser import fill_list
I/O Contract
get_value_from_path
| Parameter |
Type |
Description
|
object |
Optional[Union[str, List[Any], Dict[Any, Any]]] |
The data structure to read from
|
property_path |
str |
Dot-separated JSON Path (e.g., $.person.name)
|
| Returns |
Type |
Description
|
| Value |
Any |
The value at the specified path, or None if the object is None
|
write_value_to_path
| Parameter |
Type |
Description
|
write_object |
Union[str, List[Any], Dict[Any, Any]] |
The data structure to write into
|
property_path |
str |
Dot-separated JSON Path specifying where to write
|
value |
Any |
The value to write at the specified path
|
| Returns |
Type |
Description
|
| Modified object |
Any |
The modified data structure with the value written at the specified path
|
fill_list
| Parameter |
Type |
Description
|
desired_length |
int |
The target index that must be reachable
|
array |
list |
The list to pad
|
| Returns |
Type |
Description
|
| Padded list |
list |
The input list padded with None values to length desired_length + 1
|
get_all_paths
| Parameter |
Type |
Description
|
json_schema |
Dict[str, Any] |
The JSON Schema to analyze
|
paths |
Optional[Set[str]] |
Accumulator set for recursive calls (default: None)
|
json_path |
str |
The current JSON Path prefix (default: "$")
|
| Returns |
Type |
Description
|
| All paths |
Set[str] |
Set of all possible JSON Paths defined by the schema, including wildcard paths for open-ended objects
|
Usage Examples
from guardrails.schema.parser import get_value_from_path, write_value_to_path, get_all_paths
# Reading a value from a nested dictionary
data = {"person": {"name": "Alice", "age": 30}}
name = get_value_from_path(data, "$.person.name")
# name: "Alice"
# Writing a value to a nested path
data = {"person": {}}
result = write_value_to_path(data, "$.person.email", "alice@example.com")
# result: {"person": {"email": "alice@example.com"}}
# Extracting all paths from a JSON Schema
schema = {
"type": "object",
"properties": {
"name": {"type": "string"},
"address": {
"type": "object",
"properties": {
"city": {"type": "string"},
"zip": {"type": "string"},
}
},
"tags": {
"type": "array",
"items": {"type": "string"}
}
}
}
paths = get_all_paths(schema)
# paths: {"$", "$.name", "$.address", "$.address.city", "$.address.zip", "$.tags"}
Related Pages
