Skip to content

Fields

Field descriptors for defining keys, indexes, TTL, and discriminators.

fields

Field descriptors for Dynantic model definitions.

Provides Key, SortKey, GSIKey, GSISortKey, TTL, and Discriminator field factories for defining DynamoDB table schemas.

Key 

Key(
    default: Any = ..., *, auto: bool = False, **kwargs: Any
) -> Any

Marks a Pydantic field as a DynamoDB Primary Key (Partition Key).

Usage

email: str = Key() item_id: UUID = Key(auto=True) # Auto-generates UUID4

Parameters:

Name Type Description Default
default Any

Default value for the field

 ...
auto bool

If True, auto-generates a UUID4 on instantiation. Field should be typed as UUID. Cannot be combined with an explicit default.

 False
**kwargs Any

Additional Pydantic Field arguments

 {}
Source code in dynantic/fields.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def Key(default: Any = ..., *, auto: bool = False, **kwargs: Any) -> Any:
    """
    Marks a Pydantic field as a DynamoDB Primary Key (Partition Key).

    Usage:
        email: str = Key()
        item_id: UUID = Key(auto=True)  # Auto-generates UUID4

    Args:
        default: Default value for the field
        auto: If True, auto-generates a UUID4 on instantiation.
              Field should be typed as UUID. Cannot be combined with an explicit default.
        **kwargs: Additional Pydantic Field arguments
    """
    json_schema_extra = kwargs.pop("json_schema_extra", {})
    json_schema_extra["_dynamo_pk"] = True

    if auto:
        if default is not ...:
            raise ValueError("Cannot use Key(auto=True) with an explicit default value")
        json_schema_extra["_dynamo_auto_uuid"] = True
        return Field(
            default_factory=uuid4,
            json_schema_extra=json_schema_extra,
            **kwargs,
        )

    return Field(default, json_schema_extra=json_schema_extra, **kwargs)

SortKey 

SortKey(
    default: Any = ..., *, auto: bool = False, **kwargs: Any
) -> Any

Marks a Pydantic field as a DynamoDB Sort Key.

Parameters:

Name Type Description Default
default Any

Default value for the field

 ...
auto bool

If True, auto-generates a UUID4 on instantiation. Field should be typed as UUID. Cannot be combined with an explicit default.

 False
**kwargs Any

Additional Pydantic Field arguments

 {}
Source code in dynantic/fields.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
def SortKey(default: Any = ..., *, auto: bool = False, **kwargs: Any) -> Any:
    """
    Marks a Pydantic field as a DynamoDB Sort Key.

    Args:
        default: Default value for the field
        auto: If True, auto-generates a UUID4 on instantiation.
              Field should be typed as UUID. Cannot be combined with an explicit default.
        **kwargs: Additional Pydantic Field arguments
    """
    json_schema_extra = kwargs.pop("json_schema_extra", {})
    json_schema_extra["_dynamo_sk"] = True

    if auto:
        if default is not ...:
            raise ValueError("Cannot use SortKey(auto=True) with an explicit default value")
        json_schema_extra["_dynamo_auto_uuid"] = True
        return Field(
            default_factory=uuid4,
            json_schema_extra=json_schema_extra,
            **kwargs,
        )

    return Field(default, json_schema_extra=json_schema_extra, **kwargs)

GSIKey 

GSIKey(
    index_name: str, default: Any = ..., **kwargs: Any
) -> Any

Marks a Pydantic field as a Global Secondary Index (GSI) Partition Key.

Usage

customer_id: str = GSIKey(index_name="customer-index")

Architectural Note:

This function wraps the standard Pydantic Field. It injects a hidden flag ('_dynamo_gsi_pk') into 'json_schema_extra' along with the index name. The DynamoMeta metaclass will inspect this flag at class creation time to identify GSI partition keys and build the GSI metadata.

Parameters:

Name Type Description Default
index_name str

Name of the Global Secondary Index

 required
default Any

Default value for the field

 ...
**kwargs Any

Additional Pydantic Field arguments

 {}

Returns:

Type Description
Any

Pydantic Field instance with GSI metadata
Source code in dynantic/fields.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def GSIKey(index_name: str, default: Any = ..., **kwargs: Any) -> Any:
    """
    Marks a Pydantic field as a Global Secondary Index (GSI) Partition Key.

    Usage:
        customer_id: str = GSIKey(index_name="customer-index")

    Architectural Note:
    -------------------
    This function wraps the standard Pydantic Field. It injects a hidden flag
    ('_dynamo_gsi_pk') into 'json_schema_extra' along with the index name.
    The DynamoMeta metaclass will inspect this flag at class creation time to
    identify GSI partition keys and build the GSI metadata.

    Args:
        index_name: Name of the Global Secondary Index
        default: Default value for the field
        **kwargs: Additional Pydantic Field arguments

    Returns:
        Pydantic Field instance with GSI metadata
    """
    # Extract existing extra dict or create new one
    json_schema_extra = kwargs.pop("json_schema_extra", {})

    # Inject our internal flag with index name
    json_schema_extra["_dynamo_gsi_pk"] = index_name

    # Return a standard Pydantic Field.
    # The '...' (Ellipsis) is Pydantic's way of saying "Required field" if no default is provided.
    return Field(default, json_schema_extra=json_schema_extra, **kwargs)

GSISortKey 

GSISortKey(
    index_name: str, default: Any = ..., **kwargs: Any
) -> Any

Marks a Pydantic field as a Global Secondary Index (GSI) Sort Key.

Usage

order_date: str = GSISortKey(index_name="status-date-index")

Architectural Note:

This function wraps the standard Pydantic Field. It injects a hidden flag ('_dynamo_gsi_sk') into 'json_schema_extra' along with the index name. The DynamoMeta metaclass will inspect this flag at class creation time to identify GSI sort keys and build the GSI metadata.

Parameters:

Name Type Description Default
index_name str

Name of the Global Secondary Index

 required
default Any

Default value for the field

 ...
**kwargs Any

Additional Pydantic Field arguments

 {}

Returns:

Type Description
Any

Pydantic Field instance with GSI metadata
Source code in dynantic/fields.py 
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def GSISortKey(index_name: str, default: Any = ..., **kwargs: Any) -> Any:
    """
    Marks a Pydantic field as a Global Secondary Index (GSI) Sort Key.

    Usage:
        order_date: str = GSISortKey(index_name="status-date-index")

    Architectural Note:
    -------------------
    This function wraps the standard Pydantic Field. It injects a hidden flag
    ('_dynamo_gsi_sk') into 'json_schema_extra' along with the index name.
    The DynamoMeta metaclass will inspect this flag at class creation time to
    identify GSI sort keys and build the GSI metadata.

    Args:
        index_name: Name of the Global Secondary Index
        default: Default value for the field
        **kwargs: Additional Pydantic Field arguments

    Returns:
        Pydantic Field instance with GSI metadata
    """
    # Extract existing extra dict or create new one
    json_schema_extra = kwargs.pop("json_schema_extra", {})

    # Inject our internal flag with index name
    json_schema_extra["_dynamo_gsi_sk"] = index_name

    # Return a standard Pydantic Field.
    # The '...' (Ellipsis) is Pydantic's way of saying "Required field" if no default is provided.
    return Field(default, json_schema_extra=json_schema_extra, **kwargs)

TTL 

TTL(default: Any = ..., **kwargs: Any) -> Any

Marks a Pydantic field as the DynamoDB TTL (Time To Live) attribute.

The field should be typed as datetime (auto-converted to epoch seconds) or int (passed through as epoch seconds).

Usage

expires_at: datetime = TTL()

Note

TTL must be enabled on the DynamoDB table separately (via Terraform/CLI). Dynantic only handles correct serialization of the field value.

Parameters:

Name Type Description Default
default Any

Default value for the field

 ...
**kwargs Any

Additional Pydantic Field arguments

 {}

Returns:

Type Description
Any

Pydantic Field instance with TTL metadata
Source code in dynantic/fields.py 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
def TTL(default: Any = ..., **kwargs: Any) -> Any:
    """
    Marks a Pydantic field as the DynamoDB TTL (Time To Live) attribute.

    The field should be typed as `datetime` (auto-converted to epoch seconds)
    or `int` (passed through as epoch seconds).

    Usage:
        expires_at: datetime = TTL()

    Note:
        TTL must be enabled on the DynamoDB table separately (via Terraform/CLI).
        Dynantic only handles correct serialization of the field value.

    Args:
        default: Default value for the field
        **kwargs: Additional Pydantic Field arguments

    Returns:
        Pydantic Field instance with TTL metadata
    """
    json_schema_extra = kwargs.pop("json_schema_extra", {})
    json_schema_extra["_dynamo_ttl"] = True
    return Field(default, json_schema_extra=json_schema_extra, **kwargs)

Discriminator 

Discriminator(default: Any = ..., **kwargs: Any) -> Any

Marks a Pydantic field as the discriminator for polymorphic models.

The discriminator field is used in single-table design to differentiate between different entity types stored in the same table.

Usage

entity_type: str = Discriminator()

Architectural Note:

This function wraps the standard Pydantic Field. It injects a hidden flag into json_schema_extra. The DynamoMeta metaclass will use this to: 1. Identify which field holds the discriminator value 2. Enable polymorphic deserialization in queries/scans

Parameters:

Name Type Description Default
default Any

Default value for the field

 ...
**kwargs Any

Additional Pydantic Field arguments

 {}

Returns:

Type Description
Any

Pydantic Field instance with discriminator metadata
Source code in dynantic/fields.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
def Discriminator(default: Any = ..., **kwargs: Any) -> Any:
    """
    Marks a Pydantic field as the discriminator for polymorphic models.

    The discriminator field is used in single-table design to differentiate
    between different entity types stored in the same table.

    Usage:
        entity_type: str = Discriminator()

    Architectural Note:
    -------------------
    This function wraps the standard Pydantic Field. It injects a hidden flag
    into json_schema_extra. The DynamoMeta metaclass will use this to:
    1. Identify which field holds the discriminator value
    2. Enable polymorphic deserialization in queries/scans

    Args:
        default: Default value for the field
        **kwargs: Additional Pydantic Field arguments

    Returns:
        Pydantic Field instance with discriminator metadata
    """
    # Extract existing extra dict or create new one
    json_schema_extra = kwargs.pop("json_schema_extra", {})

    # Inject our internal flag
    json_schema_extra["_dynamo_discriminator"] = True

    # Return a standard Pydantic Field.
    # The '...' (Ellipsis) is Pydantic's way of saying "Required field" if no default is provided.
    return Field(default, json_schema_extra=json_schema_extra, **kwargs)