Skip to content

Application rules and validation with I/O

An application rule checks a condition on a value already converted to its declared type. Add it to a field’s metadata using Field[T, ...], alongside structural constraints. For checks included with Orionis, see the complete rule and constraint reference.

Declare the schema as an HTTP action parameter: the container validates the request body and awaits its rules before injecting the instance. The action runs only when validation succeeds. The same pipeline combines structural constraints, local rules, and asynchronous I/O rules. Schemas do not depend on controllers: reuse their rules in MCP, Realtime, and other entry points.

Import Empty and NoEmpty from orionis.schemas.rules to require an empty or present value. They are exact opposites and share this definition:

Value categoryEmpty when
NullThe value is None.
TextThe string is "" or contains only whitespace, including tabs and line breaks.
Numbers and booleansThe value is numeric zero, including 0, 0.0, equivalent Decimal or Fraction zeros, or False.
Sized collections and binary dataThe length is zero: lists, tuples, dictionaries, sets, arrays, bytes, and other sized values.
Uploaded filesThe file’s byte size is zero. The checks use its metadata without reading the content.

"0" is a non-empty string. [None], {"key": None}, and b" " are also non-empty because they contain elements or bytes. The rules do not inspect collection elements recursively or trim stored strings. An iterator without a length is considered present; neither rule consumes it to discover whether it yields values.

DeclarationAccepted valueFailure codeDefault message
Empty(*, message=None)Any value classified as empty.emptyValue must be empty.
NoEmpty(*, message=None)Any value not classified as empty.no_emptyValue must not be empty.

Both accept a keyword-only message: str | None = None. For example:

from orionis.schemas import Schema
from orionis.schemas.fields import Field
from orionis.schemas.rules import Empty, NoEmpty
from orionis.schemas.validator import Schema as Validator
class ReservationInput(Schema):
name: Field[str, NoEmpty(message="Name is required.")]
reserved: Field[str | None, Empty(message="Leave this field empty.")] = None
async def validate_reservation() -> ReservationInput:
payload = {"name": " Book ", "reserved": " "}
result = await Validator.validate(payload, ReservationInput)
assert result.name == " Book "
assert result.reserved == " "
assert payload == {"name": " Book ", "reserved": " "}
return result

Whitespace-only name fails with no_empty and the custom message; text in reserved fails with empty. The surrounding spaces in an accepted value remain unchanged.

These rules do not make a field optional or bypass its declared type. An absent required field still produces missing; None for Field[int, Empty()] produces type. If the type permits None, Empty() accepts it and NoEmpty() rejects it. A default such as reserved = None controls omission separately.

When a field uses Coerce(), the rules receive its converted value. For example, Field[int, Coerce(), NoEmpty()] rejects the input "0" with no_empty after conversion to 0, while Field[str, NoEmpty()] accepts the same string. Failed conversion remains a type error. See the combined example and nested error paths.

Import Rule from orionis.schemas.rule and subclass it. The executor recognizes Rule instances; implementing only the IRule contract is not sufficient to attach a rule to a schema.

ComponentResponsibility
async def enforce(field, value, instance) -> boolSingle check method for both local conditions and I/O: returns True for a valid value or False to report an error.
field: strField path, such as address.code, contacts[0].email, or contacts['primary'].email.
value: objectContains the current field’s converted value.
instance: objectProvides access to other available fields on the same object.
__code__Identifier published in errors[field][i]["rule"] and ValidationFailure.rule. Defaults to the lowercase class name when omitted.
__message__Default message for an invalid value. Define a useful description for the error recipient.
Rule(message=...)Overrides the default message for this declaration. Pass the argument by keyword.

You do not need to override async validate(): the inherited implementation calls await self.enforce(field, value, instance). When the check returns False, it constructs a ValidationFailure containing the field, code, and message; it returns None for a valid value.

Declare enforce() with async def even when its calculation contains no await. A synchronous def enforce(...) override raises TypeError when the class is defined. There is no alternate enforceAsync() method or automatic adaptation of synchronous rules; subclasses may also inherit an existing asynchronous implementation.

A rule reports an invalid value by returning False. Exceptions raised by its logic propagate; they are not automatically converted into validation failures.

From the project root, use either command:

Terminal window
orionis make:http-schema-rule EvenRule
Terminal window
python -B reactor make:http-schema-rule EvenRule

The command creates app/http/schemas/rules/evenrule.py with a Rule subclass, __code__ = "custom_rule", __message__ = "The value is invalid.", and async def enforce(self, field, value, instance) -> bool. The path follows app_http_schemas_rules; the Rule suffix is added when missing. Existing files are not overwritten.

Replace the code and message with your condition’s values and implement enforce: the template raises NotImplementedError until that logic is completed. For the next example, name the class EvenRule and use EvenRule() on the field, or retain the independent example’s Even class.

This rule combines with a numeric constraint. Type and bound checks happen during conversion; the parity condition is awaited afterwards. Its async def enforce() needs no internal await because it only calculates a local condition.

from orionis.http.base import BaseController
from orionis.schemas import Schema
from orionis.schemas.constraints import GreaterThanOrEqual
from orionis.schemas.fields import Field
from orionis.schemas.rule import Rule
class Even(Rule):
__slots__ = ()
__code__ = "even"
__message__ = "Quantity must be even."
async def enforce(
self,
field: str,
value: object,
instance: object,
) -> bool:
return isinstance(value, int) and value % 2 == 0
class Batch(Schema):
quantity: Field[int, GreaterThanOrEqual(1), Even()]
class PreviewBatchController(BaseController):
async def __call__(self, payload: Batch) -> Batch:
return payload

Save these classes in app/http/controllers/preview_batch_controller.py to follow the example. They are shown together for clarity; the rule and schema can live in separate modules. Register the controller in the configured API routes file:

from app.http.controllers.preview_batch_controller import PreviewBatchController
from orionis.support.facades import Route
Route.post("/batches/preview", PreviewBatchController)

Send POST /batches/preview with Content-Type: application/json:

  • {"quantity": 4}: the controller receives payload.quantity == 4 and returns the schema as JSON with status 200.
  • {"quantity": 3}: Even returns False; the controller does not run, and default API handling responds with status 422 and the following body:
{
"message": "Quantity must be even.",
"errors": {
"quantity": [
{"rule": "even", "message": "Quantity must be even."}
]
}
}

You do not need to receive Request or call the validator manually: the payload: Batch annotation triggers request-body validation and injection. This response applies to API routes; see the API and WEB handling differences.

__slots__ = () prevents adding an attribute dictionary to this subclass without its own configuration; it does not change the validation condition. If the rule accepts constructor configuration, declare its attributes and call super().__init__(message=message) to preserve the code and message.

Another schema can change the text using Even(message="Use an even quantity."). Field aliases typing.Annotated: rules are metadata, rather than arguments to a field-construction function.

Implement the same async def enforce() and await the actual asynchronous API. This example queries the resolver through the loop’s getaddrinfo(); the valid input uses localhost, and the invalid input is rejected before querying DNS.

import asyncio
import socket
from orionis.http.base import BaseController
from orionis.schemas import Schema
from orionis.schemas.fields import Field
from orionis.schemas.rule import Rule
class ResolvableHost(Rule):
__slots__ = ()
__code__ = "resolvable_host"
__message__ = "Host must resolve through DNS."
async def enforce(
self,
field: str,
value: object,
instance: object,
) -> bool:
if not isinstance(value, str) or not value:
return False
try:
await asyncio.get_running_loop().getaddrinfo(
value,
None,
family=socket.AF_UNSPEC,
type=socket.SOCK_STREAM,
)
except (OSError, UnicodeError):
return False
return True
class Server(Schema):
host: Field[str, ResolvableHost()]
class CheckServerController(BaseController):
async def __call__(self, payload: Server) -> Server:
return payload

In app/http/controllers/check_server_controller.py, the controller receives Server in the same way as Batch. Register its API endpoint:

from app.http.controllers.check_server_controller import CheckServerController
from orionis.support.facades import Route
Route.post("/servers/check", CheckServerController)

With Content-Type: application/json, POST /servers/check accepts {"host": "localhost"} when the local resolver resolves it; it returns {"host": "localhost"} with status 200. With {"host": ""}, the rule rejects the value before querying DNS and the action does not run. The default API response has status 422:

{
"message": "Host must resolve through DNS.",
"errors": {
"host": [
{"rule": "resolvable_host", "message": "Host must resolve through DNS."}
]
}
}

ResolvableHost uses the same contract as Even: Rule.validate() awaits its enforce(). Orionis already includes ActiveUrl to check a URL’s hostname; this example demonstrates the contract with a field containing only a hostname.

Declaring async def does not make a blocking operation asynchronous. The pipeline awaits the rule on the current loop without automatically moving its method to a worker thread. Use asynchronous I/O APIs; explicitly adapt a blocking synchronous API when needed. Brief local conditions, such as parity, are calculated directly.

Fields and rules are processed in order. Each asynchronous check is awaited before starting the next; the validator does not launch every query in parallel.

An unexpected rule exception interrupts that traversal and propagates. Cancellation of a suspended validation also propagates instead of becoming a field failure. Catch only errors that your rule considers invalid input, such as the resolver errors caught in this example.

ActiveUrl checks hostname DNS resolution for a URL; it does not request the HTTP resource or inspect its content. Inside the pipeline, it uses the loop’s resolver.

Unique queries the database through the current loop’s connection and preserves its transaction. It requires a configured connection and access to the specified table. This check does not replace a database uniqueness constraint against concurrent writes.

Rules that read file contents, such as Image, Dimensions, and Encoding’s file check, await a helper that runs the file’s synchronous read() in a worker thread. This specifically adapts that read; it does not mean every rule runs in a thread.

See their signatures, parameters, and examples in the native reference.

After successful whole-object conversion, instance is the schema owning the field. If another value fails conversion, the collector still executes rules on valid fields: that traversal provides an object containing successfully converted fields, which may omit missing or invalid fields and their defaults.

For a cross-field rule, use a defensive read such as getattr(instance, "other_field", None) and explicitly decide how to handle an unavailable value. Do not rely on instance always having a particular class, or on an earlier rule transforming another field.

Rules on a field execute in declaration order and may contribute several errors. The executor does not stop at the first False. A rule also receives None when the declared type allows it; decide whether to accept that value.

Orionis does not require a directory for custom rules. Organize them by responsibility, for example under app/validation/rules/, and import each class from the schemas that need it. Creating a rule is independent from generating a schema.

Instances declared as metadata and their plans are reused. Store only stable configuration in a rule; do not retain the request, current value, or results from an earlier validation in shared attributes. Use local variables for invocation-specific data.

The executor awaits rules in direct child schemas and elements nested in lists, dictionaries, tuples, sets, and frozen sets compatible with conversion. It also traverses compatible annotations and unions: an allowed None value is skipped as a child. Dictionaries traverse their values; set indices reflect iteration order rather than a stable position. See the collection and error examples.

Cross-field checks on a child receive that child’s fields, rather than its parent’s fields or another collection element’s fields. When one element fails conversion, the collector preserves that failure and continues awaiting rules on fields and elements it could convert.

The controller and HTTP integration guide explains how the same pipeline is awaited when a schema is declared as an action parameter.

Schemas and rules also work with data received through MCP, Realtime, tasks, or services. The integration guide distinguishes injection available in each context from explicit validation. For the latter, import Schema as Validator from orionis.schemas.validator and use await Validator.validate(data, Batch) inside an asynchronous method. In an action with payload: Batch, the container already performs that work; do not repeat it. The error guide explains when to catch ValidationException.