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 path data.nested.int.

  • The field my_str maps to the path metadata.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:

  1. Simple Path data.info.name Accesses the name key inside the info object within data.

  2. Array Indexing data[0].value Accesses the value field in the first element of the data array.

  3. Keys with Spaces or Special Characters metadata["user name"].details Accesses the details key inside metadata["user name"].

  4. Mixed Types data[0]["user name"].info.age Accesses age within info, nested under "user name" in the first item of data.

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 the True key in the user object. Booleans like True and False are automatically recognized.

  • Example 2: Integer Path

    split_object_path('data[5].value')
    

    Output: ['data', 5, 'value'] Accesses value in the 6th element (index 5) of the data 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'] Accesses age within info, under user name, in the first item of data.

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 with KeyPath() 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.