pre-alpha

2.8 · Tutorial

7. Validate input

Schema validation combines built-in type and value constraints with optional synchronous normalization and rejection checks. Constraints reject invalid input first; normalizers canonicalize valid strings; checks can then reject values based on one field or compare several fields. All of this happens before a validated schema reaches an operation.

from typing import Annotated

from hinoki import (
    Field,
    Invalid,
    Schema,
    errors,
    field_check,
    field_normalize,
    object_check,
)


class Registration(Schema):
    username: Annotated[
        str,
        Field(min_length=3, max_length=32, pattern=r"[a-z0-9_]+"),
    ]
    email: Annotated[str, Field(format="email")]
    password: Annotated[str, Field(min_length=12)]
    confirmation: str

    @field_normalize("email")
    def lowercase_email(self, value: str) -> str:
        return value.lower()

    @field_check("password")
    def reject_common_password(self, value: str) -> None:
        if value.lower() in {"password12345", "qwerty123456"}:
            raise Invalid("common_password", "choose a less common password")

    @object_check
    def passwords_match(self) -> None:
        if self.password != self.confirmation:
            raise Invalid(
                "password_mismatch",
                "passwords do not match",
                path="confirmation",
            )


valid = Registration.validate(
    {
        "username": "mari_23",
        "email": "mari@example.test",
        "password": "correct-horse-battery",
        "confirmation": "correct-horse-battery",
    }
)
assert valid.username == "mari_23"
assert valid.email == "mari@example.test"
try:
    Registration.validate(
        {
            "username": "mari_23",
            "email": "mari@example.test",
            "password": "password12345",
            "confirmation": "different-password",
        }
    )
except errors.ValidationError as error:
    for detail in error.details:
        print(detail.path, detail.code, detail.message)

The invalid call reports a common_password error on password and a password_mismatch error on confirmation. min_length, max_length and pattern are built-in field constraints. format="email" is a ready-made pattern; url, slug and hex_color are also available. Numeric fields can use gt, ge, lt and le, and one_of restricts a value to a fixed set. An invalid built-in constraint prevents normalizers and custom checks from running.

@field_normalize("email") receives a structurally valid string and must return a str. Its result is checked against the same constraints before it is applied. Normalization also runs when you manually construct a Schema(...) or call from_model(...); it does not run twice when an existing nested Schema is passed to a new parent. Inputs that fail the original constraints cannot be rescued by normalization.

@field_check("password") receives the final value. @object_check receives the complete schema and can compare final fields. Raise Invalid(code, message) to report a failure; checks must return None and do not transform the value. Normalizers and checks are synchronous, have no I/O, and run the same way before both sync and async handlers. A check that needs current database state, such as whether an email is already registered, belongs in an operation where it can be made race-safe.

Ignore unknown fields from external payloads

Unknown fields are rejected by default. For an external payload that adds unrelated metadata, opt in to discarding unknown string keys on that Schema:

from hinoki import Schema, SchemaConfig, SchemaExtra


class Webhook(Schema, config=SchemaConfig(extra=SchemaExtra.IGNORE)):
    event_id: str
    revision: int


event = Webhook.validate(
    {"event_id": "evt-1", "revision": 2, "provider_data": {"trace": "abc"}}
)
assert event.dump() == {"event_id": "evt-1", "revision": 2}

Known fields still require the declared types and constraints, and required fields remain required. Ignored keys are discarded; they are never attached to the object or returned by dump(). The policy affects Schema.validate(...) and request bodies before sync or async handlers. Constructor keywords and explicit from_model(..., **extra) overrides remain strict. Nested Schemas each use their own policy. Aliases also remain canonical: a Python field name does not substitute for its alias, and supplying both spellings is still an error.

Validate values at Model write boundaries

Use the same built-in constraints on Model fields when data can be written outside an HTTP Schema, such as from a management command or the admin. Custom callbacks are synchronous and raise ValueError to refuse a value:

from uuid import UUID, uuid4

from hinoki import Field
from hinoki.orm import Model, field


def normalized(value: str) -> None:
    if value != value.strip():
        raise ValueError("surrounding whitespace is not allowed")


class Product(Model):
    id: UUID = field(primary_key=True, default_factory=uuid4)
    sku: str = field(
        max_length=32,
        constraints=Field(min_length=3, pattern=r"[A-Z0-9-]+"),
    )
    name: str = field(max_length=120, validators=(normalized,))
    price: float = field(constraints=Field(gt=0))

The checks run before await Product.acreate(...), await product.asave() and await Product.filter(...).aupdate(...), as well as their synchronous counterparts. Construction and assignment stay ordinary dataclass operations; existing rows are not revalidated when read. Invalid writes raise ModelValidationError with structured details, and no SQL is issued for that write. Validators must not perform I/O or change values. Keep request parsing in a Schema, and put rules that depend on other rows or permissions in an operation. See Model field constraints and validators.

More: Schema constraints and checks, schemas derived from models.