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>Requestde entrada y<Entidad>Responsede salida (CanalComercialCrearRequest,CanalComercialResponse): negocio en español, sufijo técnico en inglés (ADR 0004 transversal). - Un
schemas.pypor dominio. La baseAuditoriaCampos(id,is_activo,created_at,updated_at,from_attributes=True) vive enapp/shared/schemas.py, porque la usancatalogosyclientes; no encore/. - 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=Trueyextra="forbid": un campo no declarado (empresa_id,id,is_activo) responde 422 en vez de ignorarse. - Salida sin
empresa_idnideleted_at: un borrado se ve conis_activo = false. - En
*ActualizarRequestno van el código (clave de negocio) niis_activo(desactivar es borrar).
Alternativas descartadas¶
Request/Responsedice de qué lado viaja el contrato.AuditoriaCamposenapp/core/schemas.py—core/es infraestructura técnica; un contrato que comparten dominios de este servicio va enshared/.- Un solo contrato genérico para todos los catálogos — el OpenAPI tendría un
único
CatalogoResponsey no se distinguiría un catálogo de otro. - Ignorar campos extra (comportamiento por defecto de Pydantic) — un
empresa_iden 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.
AuditoriaCamposnació encatalogos/schemas.pyy pasó aapp/shared/al sumarse el dominioclientes(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.