Saltar a contenido

0005. Contratos de API con schemas Pydantic

Estado: Propuesto Fecha: 2026-09-29 Autor: Kevin Delgado Lopez Módulo(s) afectado(s): app/domains/*/schemas.py

Contexto

Con los modelos ORM listos (ADR 0004) la API necesita contratos tipados de entrada y salida. El ADR 0005 transversal separa contratos y modelos, y el nombre de cada contrato es el que aparece en el OpenAPI. Además, quien consume la API nunca debe poder fijar la empresa ni campos que controla el servidor.

Decisión

  • Nombres <Entidad><Accion>Request de entrada y <Entidad>Response de salida (CanalComercialCrearRequest, CanalComercialResponse): negocio en español, sufijo técnico en inglés (ADR 0004 transversal).
  • Un schemas.py por dominio. La base AuditoriaCampos (id, is_activo, created_at, updated_at, from_attributes=True) vive en app/shared/schemas.py, porque la usan catalogos y clientes; no en core/.
  • Tablas con la misma forma heredan de bases comunes (CatalogoCrearRequest, CatalogoActualizarRequest, CatalogoResponse), pero cada tabla tiene sus propias clases para que el OpenAPI las nombre por separado.
  • Entrada con str_strip_whitespace=True y extra="forbid": un campo no declarado (empresa_id, id, is_activo) responde 422 en vez de ignorarse.
  • Salida sin empresa_id ni deleted_at: un borrado se ve con is_activo = false.
  • En *ActualizarRequest no van el código (clave de negocio) ni is_activo (desactivar es borrar).

Alternativas descartadas

  • Request/Response dice de qué lado viaja el contrato.
  • AuditoriaCampos en app/core/schemas.py — core/ es infraestructura técnica; un contrato que comparten dominios de este servicio va en shared/.
  • Un solo contrato genérico para todos los catálogos — el OpenAPI tendría un único CatalogoResponse y no se distinguiría un catálogo de otro.
  • Ignorar campos extra (comportamiento por defecto de Pydantic) — un empresa_id en el cuerpo pasaría en silencio y ocultaría errores del cliente.

Consecuencias

  • El OpenAPI tiene un tipo por tabla y por acción.
  • Hay clases casi vacías que sólo heredan; es repetición intencional.
  • La auditoría sale primero en el JSON por la herencia; no afecta a los consumidores.
  • AuditoriaCampos nació en catalogos/schemas.py y pasó a app/shared/ al sumarse el dominio clientes (ADR 0017).

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.