Validación HTTP con schemas

Los schemas describen los campos, tipos y reglas que acepta un payload. Una acción de controlador puede recibir directamente un schema validado, en lugar de leer y validar el cuerpo manualmente mediante Request.

Esta página presenta el flujo HTTP. La guía de Validación desarrolla su funcionamiento, el generador CLI, todas las reglas nativas, las reglas personalizadas y el manejo de errores.

Los mismos contratos también sirven en tools MCP, métodos remotos Realtime y otros puntos de entrada. Su guía de integraciones explica cómo se reciben los datos en cada contexto; la inyección del cuerpo que se muestra aquí es específica de HTTP.

Recibir datos validados

Anota el parámetro con una clase concreta de Schema, sin valor predeterminado:

Orionis construye e inyecta ese objeto al resolver la petición. Dentro de la acción puedes utilizar sus campos directamente; no necesitas crear el schema, leer el cuerpo ni ejecutar manualmente el validador para ese parámetro.

from orionis.http.base import BaseController
from orionis.schemas import Schema
from orionis.schemas.constraints import MinLength
from orionis.schemas.fields import Field


class ProfileInput(Schema):
    name: Field[str, MinLength(2)]


class ProfileOutput(Schema):
    name: str


class ProfileController(BaseController):
    async def __call__(self, payload: ProfileInput) -> ProfileOutput:
        return ProfileOutput(name=payload.name)

Al atender la ruta, el contenedor obtiene await request.data() y ejecuta await Validator.validate(datos, ProfileInput), donde Validator es el alias de Schema de orionis.schemas.validator. Sólo después de validar entrega payload a la acción.

Un cuerpo JSON como {"name": "Ada"} permite devolver {"name": "Ada"}. Si el nombre no cumple MinLength(2), la acción no se ejecuta. La guía de integración con controladores muestra los archivos, el registro de rutas y las respuestas completas.

La inyección valida el cuerpo: no mezcla automáticamente query string, parámetros de ruta ni cabeceras. Puedes recibir también Request cuando necesitas esos datos o controlar la lectura. La conversión es estricta; un texto numérico no se convierte automáticamente a int.

Devolver un schema

El ejemplo devuelve una instancia de ProfileOutput; el kernel la serializa como JSON con estado 200. La anotación -> ProfileOutput describe el retorno, pero no valida ni convierte automáticamente la salida. Si necesitas comprobarla, ejecuta explícitamente await Validator.validate(..., ProfileOutput) antes de devolverla.

Con el manejo predeterminado, los errores de validación producen JSON 422 en rutas API. En WEB, producen JSON 422 para solicitudes que esperan JSON o son AJAX, y una redirección 302 con errores de sesión para la navegación habitual. Consulta los detalles de entrada, salida y errores HTTP.

Guía completa de Validación

• Funcionamiento y arquitectura: schemas, restricciones, reglas y ejecución asíncrona.
• Declaración y generador CLI: make:http-schema, campos, valores predeterminados y metadatos.
• Integraciones y puntos de entrada: HTTP, MCP, Realtime, WebSockets y servicios.
• Todas las restricciones y reglas nativas: firmas y ejemplos de código para cada una.
• Reglas personalizadas: contrato y comprobaciones propias, incluidas operaciones con I/O asíncrono.
• Errores de validación: mensajes y fallos por campo.
• Controladores y respuestas: ejemplo completo de inyección, validación de salida y errores API/WEB.

Para las APIs HTTP complementarias, consulta controladores, Request y payloads y respuestas.

En servicios o handlers WebSocket simples, utiliza validación explícita con los datos ya leídos. MCP y Realtime incorporan sus propios mecanismos de validación e inyección; consulta los ejemplos de cada integración.