Map a Nested JSON Key Path to a Field¶
Note
Important: The current “nested path” functionality is being re-imagined. Please refer to the new docs for V1 Opt-in features, which introduces enhanced support for these use cases. For more details, see the Field Guide to V1 Opt‐in and the V1 Alias documentation.
This change is part of the ongoing improvements in version v0.35.0+
, and the old functionality will no longer be maintained in future releases.
The dataclass-wizard
library allows mapping deeply nested JSON paths to individual dataclass fields using a custom object path notation. This feature supports both Annotated
types and dataclasses.Field
for flexible and precise JSON deserialization.
Basic Usage Example¶
Define and use nested key paths for JSON deserialization with the Annotated
type and path_field()
:
from dataclasses import dataclass
from dataclass_wizard import JSONWizard, KeyPath, path_field
from typing import Annotated
@dataclass
class Example(JSONWizard):
# Map using Annotated with KeyPath
an_int: Annotated[int, KeyPath('data.nested.int')]
# Map using path_field with a default value
my_str: str = path_field(['metadata', 'info', 'name'], default='unknown')
The field
an_int
maps to the nested JSON pathdata.nested.int
.The field
my_str
maps to the pathmetadata.info.name
and defaults to'unknown'
if the key is missing.
Expanded Example with JSON¶
Given the following JSON data:
{
"data": {
"nested": {
"int": 42
}
},
"metadata": {
"info": {
"name": "John Doe"
}
}
}
Deserializing with the from_dict()
method:
example = Example.from_dict({
"data": {
"nested": {
"int": 42
}
},
"metadata": {
"info": {
"name": "John Doe"
}
}
})
print(example.an_int) # 42
print(example.my_str) # 'John Doe'
This example shows how JSON data is mapped to dataclass fields using the custom key paths.
Object Path Notation¶
The object path notation used in KeyPath()
and path_field()
follows these rules:
Dot (.) separates nested object keys.
Square brackets ([]) access array elements or special keys.
Quotes (”’) are required for keys with spaces, special characters, or reserved names.
Examples:
Simple Path
data.info.name
Accesses thename
key inside theinfo
object withindata
.Array Indexing
data[0].value
Accesses thevalue
field in the first element of thedata
array.Keys with Spaces or Special Characters
metadata["user name"].details
Accesses thedetails
key insidemetadata["user name"]
.Mixed Types
data[0]["user name"].info.age
Accessesage
withininfo
, nested under"user name"
in the first item ofdata
.
Path Parsing Examples¶
These examples illustrate how the path is interpreted by KeyPath
or path_field
:
Example 1: Boolean Path
split_object_path('user[true]')
Output:
['user', True]
Accesses theTrue
key in theuser
object. Booleans likeTrue
andFalse
are automatically recognized.Example 2: Integer Path
split_object_path('data[5].value')
Output:
['data', 5, 'value']
Accessesvalue
in the 6th element (index 5) of thedata
array.Example 3: Floats in Paths
split_object_path('data[0.25]')
Output:
['data', 0.25]
Floats are parsed correctly, although array indices are typically integers.Example 4: Strings Without Quotes
split_object_path('data[user_name]')
Output:
['data', 'user_name']
Valid identifiers are treated as strings even without quotes.Example 5: Strings With Quotes
split_object_path('data["user name"]')
Output:
['data', 'user name']
Quotes are required for keys with spaces or special characters.Example 6: Mixed Types
split_object_path('data[0]["user name"].info[age]')
Output:
['data', 0, 'user name', 'info', 'age']
Accessesage
withininfo
, underuser name
, in the first item ofdata
.
Handling Quotes¶
When keys or indices are wrapped in quotes, they are interpreted as strings. This is necessary for:
Keys with spaces or special characters.
Reserved words or identifiers that could otherwise cause parsing errors.
Example:
split_object_path('data["123"].info')
Output: ['data', '123', 'info']
Here, "123"
is treated as a string because of the quotes.
Best Practices¶
Use
Annotated
withKeyPath()
for complex, deeply nested paths.Use
path_field()
for flexibility, defaults, or custom serialization.Keep paths concise and use quotes judiciously for clarity and correctness.