Unions Discriminadas no Pydantic com Literal resolve um problema recorrente em projetos Python: Valide payloads com formatos alternativos usando um campo que identifica inequivocamente cada variante. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
A union comum tenta modelos em sequência; uma union discriminada lê uma tag e escolhe diretamente o modelo correspondente. Isso melhora erros e schema OpenAPI.
Para revisar os fundamentos relacionados, consulte também o guia de Pydantic. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
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: PaymentUse uma chave estável como kind e um Literal exclusivo em cada modelo. Não reutilize o mesmo valor em variantes diferentes.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Sem discriminador, mensagens podem acumular erros de todos os modelos. Alterar a tag publicada quebra consumidores e exige compatibilidade planejada.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Teste cada variante, tag desconhecida, tag ausente e campos que pertencem à variante errada. Inspecione também o JSON Schema.