Passing a BaseModel instance to an Annotated field breaks validation in nested models? #13808

leo4811 · 2026-09-14T21:32:50Z

leo4811
Sep 14, 2026

I ran into an issue when trying to annotate fields with instances of other pydantic models. My use case is that I have defined a model which contains some metadata (MetaDataModel) that I'd like to attach to certain fields on other pydantic models, to then use later during validation. The problem is that if I have a "child" model Child with a field param that is, e.g., a str annotated with an instance of MetaDataModel, and then another "parent" model Parent with a field child of type Child, then I get a validation error when trying to validate a Parent instance, with the error saying that the field child.param should be type MetaDataModel, instead of type str (see example script below).

I am wondering- is this intended behavior, or is something wrong here? I can't find much explanation of how the Annotated pattern is parsed in the docs, but maybe I'm missing something. If this is intended behavior, is there a workaround?

I'm using python version 3.13.12 and pydantic version 2.13.5.

Thanks!

from pydantic import BaseModel
from typing import Annotated


## Model containing some metadata that I want to attach to field(s) in other models
class MetaDataModel(BaseModel):
    metadata: str


## Model with non-pydantic metadata annotated on the "param" field
class NormalAnnotatedModel(BaseModel):
    param: Annotated[str, "metadata"]


print(repr(NormalAnnotatedModel.model_fields["param"]))
# -> FieldInfo(annotation=str, required=True, metadata=['metadata'])
print(repr(NormalAnnotatedModel.model_validate({"param": "test"})))
# -> NormalAnnotatedModel(param='test')


## Parent model with a child instance of the NormalAnnotatedModel, works fine
class NormalParentModel(BaseModel):
    child: NormalAnnotatedModel


print(repr(NormalParentModel.model_validate({"child": {"param": "test"}})))
# -> NormalParentModel(child=NormalAnnotatedModel(param='test'))


## Model with a pydantic model instance annotated on the "param" field
## works fine when instantiated directly...
class BrokenAnnotatedModel(BaseModel):
    param: Annotated[str, MetaDataModel(metadata="metadata")]

print(repr(BrokenAnnotatedModel.model_fields["param"]))
# -> FieldInfo(annotation=str, required=True, metadata=[MetaDataModel(metadata='metadata')])
## ^ MetaDataModel instance correctly gets categorized as metadata
print(repr(NormalAnnotatedModel(param="test")))
# -> NormalAnnotatedModel(param='test')


## Model with a child instance of BrokenAnnotatedModel
class BrokenParentModel(BaseModel):
    child: BrokenAnnotatedModel

print(repr(BrokenParentModel.model_validate({"child": {"param": "test"}})))
# Traceback (most recent call last):
#   File ...
#     print(repr(ParentModel.model_validate({"child": {"param": "test"}})))
#                ~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#   File ...
#     return cls.__pydantic_validator__.validate_python(
#            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
#         obj,
#         ^^^^
#     ...<5 lines>...
#         by_name=by_name,
#         ^^^^^^^^^^^^^^^^
#     )
#     ^
# pydantic_core._pydantic_core.ValidationError: 1 validation error for BrokenParentModel
# child.param
#   Input should be a valid dictionary or instance of MetaDataModel [type=model_type, input_value='test', input_type=str]
#     For further information visit https://errors.pydantic.dev/2.13/v/model_type

Kxrma47 · 2026-09-14T22:40:25Z

Kxrma47
Sep 14, 2026

I can reproduce this on Pydantic 2.13.5. The str annotation is not the problem; the collision is specifically that a BaseModel instance is being used as inert Annotated metadata.

Pydantic treats metadata exposing __get_pydantic_core_schema__ as schema middleware. A BaseModel instance exposes that hook, so during the nested model's schema construction it can replace the str schema with the metadata model's schema.

Use a plain immutable metadata object instead:

from dataclasses import dataclass
from typing import Annotated
from pydantic import BaseModel

@dataclass(frozen=True)
class MetaData:
    metadata: str

class Child(BaseModel):
    param: Annotated[str, MetaData("metadata")]

class Parent(BaseModel):
    child: Child

assert Parent.model_validate(
    {"child": {"param": "test"}}
) == Parent(child=Child(param="test"))

assert Child.model_fields["param"].metadata == [MetaData("metadata")]

I verified both assertions on 2.13.5. If the metadata is meant to alter validation, implement the schema hook deliberately; if it is only information you inspect later, a frozen dataclass is the safer representation.

This looks like an unintended hook collision rather than Annotated changing the declared field type. The relevant dispatch is in _get_wrapped_inner_schema; the documented pattern for custom metadata is here.

0 replies

Viicos · 2026-09-16T11:31:34Z

Viicos
Sep 16, 2026
Maintainer

See also #12096. You are unfortunately hitting edge cases of the confusing __get_pydantic_core_schema__() API.

0 replies

Vedant021004 · 2026-09-18T12:17:39Z

Vedant021004
Sep 18, 2026

This happens because in Pydantic v2, every BaseModel defines __get_pydantic_core_schema__.

When Pydantic generates schemas for nested models, its schema generator inspects all metadata objects inside Annotated[T, ...]. If any metadata object implements __get_pydantic_core_schema__, Pydantic treats it as a schema modifier/validator rather than passive metadata. As a result, MetaDataModel's schema generator is invoked and replaces the field's schema with that of MetaDataModel, which is why it complains that the input should be a valid dictionary or instance of MetaDataModel instead of str.

Workarounds / Solutions:

1. Use a standard Python `@dataclass` (Recommended)

Plain Python @dataclass classes do not implement __get_pydantic_core_schema__, so Pydantic treats them purely as metadata without interfering with field validation:

from dataclasses import dataclass
from typing import Annotated
from pydantic import BaseModel

@dataclass
class MetaDataModel:
    metadata: str

class NormalAnnotatedModel(BaseModel):
    param: Annotated[str, MetaDataModel(metadata="metadata")]

class BrokenParentModel(BaseModel):
    child: NormalAnnotatedModel

# Validates properly:
print(repr(BrokenParentModel.model_validate({"child": {"param": "test"}})))
# -> BrokenParentModel(child=NormalAnnotatedModel(param='test'))

2. Attach metadata using `Field(json_schema_extra=...)`

If MetaDataModel needs to remain a Pydantic BaseModel, you can attach its dump via Field:

from pydantic import BaseModel, Field

class MetaDataModel(BaseModel):
    metadata: str

class NormalAnnotatedModel(BaseModel):
    param: str = Field(..., json_schema_extra={"metadata": MetaDataModel(metadata="metadata").model_dump()})

0 replies

Navigation Menu

Uh oh!

Passing a BaseModel instance to an Annotated field breaks validation in nested models? #13808

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 3 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Passing a BaseModel instance to an Annotated field breaks validation in nested models? #13808

Uh oh!

Uh oh!

leo4811 Sep 14, 2026

Replies: 3 comments

Uh oh!

Kxrma47 Sep 14, 2026

Uh oh!

Viicos Sep 16, 2026 Maintainer

Uh oh!

Vedant021004 Sep 18, 2026

Workarounds / Solutions:

1. Use a standard Python @dataclass (Recommended)

2. Attach metadata using Field(json_schema_extra=...)

leo4811
Sep 14, 2026

Kxrma47
Sep 14, 2026

Viicos
Sep 16, 2026
Maintainer

Vedant021004
Sep 18, 2026

1. Use a standard Python `@dataclass` (Recommended)

2. Attach metadata using `Field(json_schema_extra=...)`