Tres paradigmas de tipos en Python
Python tiene tres enfoques principales para estructuras de datos tipadas. dataclass (de la biblioteca estándar) genera una clase con __init__, __repr__ y sugerencias de tipo — el enfoque más portátil ya que no requiere dependencias de terceros. TypedDict (módulo typing) describe la forma de un diccionario sin crear una nueva clase — preferido cuando se trabaja con código que espera dicts simples. Pydantic BaseModel añade validación en tiempo de ejecución, serialización y generación de esquemas JSON — el estándar de oro para modelos de API y gestión de configuración.
El convertidor infiere tipos de Python desde JSON: las cadenas se mapean a str, los números sin decimales a int, los números con decimales a float, los booleanos a bool, null a None (y el tipo del campo a Optional[T]), los objetos anidados a una clase anidada y los arrays a list[T]. Para arrays con elementos de tipos mixtos el tipo de elemento se convierte en Union.
Los objetos anidados generan definiciones de clase separadas colocadas encima de la clase que las referencia, respetando las reglas de referencia forward de Python sin necesitar el guard "TYPE_CHECKING" en la mayoría de casos.
Características específicas de Pydantic
Cuando se selecciona la salida Pydantic, el generador usa pydantic.BaseModel como clase base y añade anotaciones Field() para valores por defecto y descripciones donde la estructura JSON las implica. Se usa la sintaxis Pydantic v2 por defecto (model_config = ConfigDict(...)) con un toggle para compatibilidad v1 (class Config).
Los nombres de campo que son palabras reservadas de Python o contienen caracteres ilegales en identificadores Python (guiones, espacios, puntos) se renombran automáticamente usando convenciones snake_case con un argumento alias= para que Pydantic pueda seguir parseando la clave JSON original.
La opción model_config populate_by_name=True se emite por defecto para que los modelos Pydantic puedan instanciarse tanto por el alias (coincidiendo con JSON) como por el nombre del campo Python, que es el comportamiento más flexible para el código cliente de API.
Flujo de trabajo e integración
Pega cualquier respuesta JSON de API y obtén inmediatamente clases Python tipadas que puedes incluir en una ruta FastAPI, un serializador de Django REST Framework o un script de procesamiento de datos.
Al explorar un nuevo dataset, generar clases tipadas primero hace el código posterior más seguro y legible. IDEs como PyCharm y VS Code proporcionan autocompletado y verificación de tipos contra los tipos generados.
Los pipelines de ingeniería de datos se benefician de los modelos Pydantic con validación estricta: cualquier registro que no se ajuste al esquema lanza un ValidationError al principio del pipeline en lugar de fallar silenciosamente más adelante.