Add polymorphic_serialization option - #12518

Change Summary

(Imported from pydantic/pydantic-core#1881)

Introduced as a possible solution to #12382; the theory is that most uses of serialize_as_any are because users want to respect subtyping properly.

This PR introduces a configuration option and runtime flag polymorphic_serialization which is used to enable serializing subclasses of models and dataclasses as the subclass, not as the base class.

To maintain backwards compatibility, the default is False - models and dataclasses will be serialized as the exact type in the schema.

When the config is set to True, then models and dataclasess will be serialized as their runtime type. This also respects any model serializer the subclass may be using.

Users can also pass polymorphic_serialization as a runtime option to the serialization functions; doing so will override the config value (i.e. can be globally enabled or disabled).

Points of Discussion for this PR

Annotated metadata

Not explored yet in this PR, an additional / alternative possibility could be to expose this as some kind of wrapper so that for foreign types one can use Annotated[ForeignModel, PolymorphicSerialization] to enable this even when the type didn't opt in.

(An Annotated form may remove the need for the global runtime override.)

Non-Pydantic types

This method cannot really ever work for types which Pydantic doesn't know how to serialize, e.g. subclass of int will not be serialized polymorphically. If the subclass had a __pydantic_serializer__ attribute it could in theory work, but I think that's the unlikely case.

More complicated is stdlib dataclasses and TypedDict. It might be reasonable to expect these to work, but I think that would require inspection of the subclass types at runtime and somehow caching a serializer for them. (i.e. a lot of runtime callback into Pydantic.)

Backwards compatibility

For the concern listed above on non-pydantic types, one way to introduce support for them later would be to have the runtime flag accept a set of types to serialize, e.g. polymorphic_serialization = {BaseModel, BaseDataClass, int}

... but another way to avoid the problem entirely would be to not have the global runtime flag and use the Annotated form to apply this behavior only to supported types.

Related issue number

#12382

Checklist

• The pull request title is a good summary of the changes - it will be used in the changelog
• Unit tests for the changes exist
• Tests pass on CI
• Documentation reflects the changes where applicable
• My PR is ready to review, please add a comment including the phrase "please review" to assign reviewers