Uniones Discriminadas en Pydantic con Literal resuelve un problema frecuente en proyectos Python: Valida formas alternativas mediante un campo que identifica inequívocamente cada variante. Esta guía explica el mecanismo, presenta un ejemplo ejecutable y marca los límites que evitan una implementación frágil.
Concepto y caso de uso
Una unión normal prueba modelos en secuencia; una discriminada lee una etiqueta y elige directamente el modelo. Esto mejora errores y OpenAPI.
Para repasar los fundamentos relacionados, consulta también la guía de validadores Pydantic. La integración es más simple cuando cada función recibe dependencias y datos explícitamente en lugar de depender de estado global.
Ejemplo práctico
from typing import Annotated, Literal
from pydantic import BaseModel, Field
class Card(BaseModel):
kind: Literal["card"]
last_four: str
class Pix(BaseModel):
kind: Literal["pix"]
key: str
Payment = Annotated[Card | Pix, Field(discriminator="kind")]
class Order(BaseModel):
payment: PaymentUsa una clave estable como kind y un Literal exclusivo en cada modelo. No reutilices el mismo valor entre variantes.
Decisiones importantes
La elección correcta depende del contrato público, del volumen y del comportamiento ante fallos.
Considera concurrencia, entradas vacías y fallos parciales. Documenta cada límite que afecte a consumidores y usa nombres que expresen intención.
Errores frecuentes
El ejemplo mínimo no sustituye límites, manejo de errores y observabilidad. Sin discriminador, los errores pueden incluir fallos de todos los modelos. Cambiar una etiqueta publicada rompe clientes y exige compatibilidad.
Evita capturar excepciones sin contexto o devolver resultados parciales como si fueran completos. Un fallo explícito suele ser más seguro que datos silenciosamente incorrectos.
Cómo validar
Valida el comportamiento y no solo el camino feliz. Prueba cada variante, etiqueta desconocida o ausente y campos de la variante incorrecta. Inspecciona también JSON Schema.