Skip to content

HTTP validation with schemas

Schemas describe a payload’s accepted fields, types, and rules. A controller action can receive a validated schema directly instead of manually reading and validating the body through Request.

This page introduces the HTTP flow. The Validation guide covers its architecture, CLI generator, every native rule, custom rules, and error handling.

The same contracts also work in MCP tools, Realtime remote methods, and other entry points. The integration guide explains each context’s data source; the body injection shown here is specific to HTTP.

Annotate the parameter with a concrete Schema class, without a default value:

Orionis constructs and injects that object while resolving the request. Inside the action, use its fields directly; you do not need to construct the schema, read the body, or run the validator manually for that parameter.

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)

When handling the route, the container reads await request.data() and runs await Validator.validate(data, ProfileInput), where Validator aliases Schema from orionis.schemas.validator. It passes payload to the action only after validation succeeds.

A JSON body such as {"name": "Ada"} allows the action to return {"name": "Ada"}. If the name fails MinLength(2), the action does not run. The controller integration guide shows the files, route registration, and complete responses.

Injection validates the body: it does not automatically merge query strings, route parameters, or headers. You can also receive Request when you need those values or control body reading. Fields outside the scope of Coerce() remain strict; numeric text does not automatically become an int. A marker on a parent schema or collection also enables conversion for descendant values. Since 1.4.0, Coerce() enables conversion on selected fields before validation, including numeric form fields. Empty() and NoEmpty() inspect the converted values without trimming strings or changing the original payload.

The example returns a ProfileOutput instance; the framework validates its types, constraints, and rules before serializing it as JSON with status 200. This check depends on the returned instance, even without a return annotation. -> ProfileOutput alone does not convert a dictionary into a schema. Responses that are not direct Schema instances do not enter this validation.

With default handling, input validation failures produce JSON 422 in API routes, with lists of {rule, message} objects per field. In WEB, they produce JSON 422 for requests expecting JSON or using AJAX, and a 302 redirect with session errors for ordinary navigation. An invalid Schema output produces a server error 500. See input, output, and HTTP error details.

For the related HTTP APIs, see controllers, Request and payloads, and responses.

In services or plain WebSocket handlers, explicitly validate data you have already read. MCP and Realtime provide their own validation and injection mechanisms; see the examples for each integration.