3.4 · Guides
Schemas¶
A Schema describes data that crosses the API boundary and validates it strictly. Models describe tables; a column reaches a client only when a Schema names it.
from typing import Annotated
from uuid import UUID
from hinoki import Field, Schema
class NoteIn(Schema):
title: Annotated[str, Field(min_length=1, max_length=80)]
body: str = ""
class NoteOut(Schema):
id: UUID
title: str
body: str
- Strict, no coercion.
"1"is not1(Schema.validate_text()andForm[Schema],XML[Schema],Query[Schema]are the explicit text-source exception, below); unknown keys are refused by default; every problem is reported with its path (capped at 50). Validation, instance construction and JSON serialisation run in Rust. - Partial updates. Declare
title: str | Unset = UNSET: a field the client did not send staysUNSETand is left out ofdump()andto_dict(), sorow.aupdate_from(patch)writes only what was sent. - Get data out.
schema.to_dict()gives Python values (UUID and datetime stay objects),schema.dump()the JSON-compatible form; both skipUNSET. - From rows.
NoteOut.from_model(row, author_name=row.author.name)converts one row;NoteOut.from_models(rows)eagerly converts a synchronous iterable to a list. Relations must already be loaded (nothing fetches lazily). A derived schema keeps its selected fields. Conversion reads the expected attributes rather than checking the concrete model class; missing attributes raiseAttributeError. Values passed as**extraare shared across rows. - Into a row.
await Note.acreate(data, author_id=me)andawait row.aupdate_from(patch): keyword values set by the server win over the client's, and a schema can never carry the primary key.
Schema.validate(data) reports structural problems together. Values are not coerced; for data that is all text, such as form fields, Schema.validate_text(data) first converts values to the int, float and bool fields declare (and wraps a lone value of a list field), in Rust, then runs the same strict validate. A value that does not convert is left as text and fails validation with the usual type error; str, UUID and datetime are checked as text. Declare field constraints with Field(...); use @field_normalize for narrow, typed string canonicalization and @field_check/@object_check for synchronous rejection checks.
Field types¶
A field is annotated with str, int, float, bool, UUID, datetime, date, time, timedelta, Decimal, bytes, an Enum class, a Literal, a nested Schema, a TypedDict or dataclass, list[X], set[X], frozenset[X], tuple[X, ...], tuple[X, Y], dict[str, X] or a discriminated union, a plain union such as int | str, Any, optionally | None (accepts null) and | Unset (may be left out of a partial update), and optionally wrapped in Annotated[..., Field(...)]. X can be any of these, so list[dict[str, int]] and dict[str, list[Point]] work. Anything else (bytearray, dict[int, X]) raises RegistrationError when the class is created.
Sets and tuples¶
set[X], frozenset[X], tuple[X, ...] and fixed tuples such as tuple[float, float] travel as JSON arrays; validation returns the Python container:
from typing import Annotated
from hinoki import Field, Schema
from hinoki.errors import ValidationError
class Place(Schema):
tags: Annotated[set[str], Field(max_length=5)]
point: tuple[float, float]
path: tuple[int, ...] = ()
place = Place.validate({"tags": ["a", "b", "a"], "point": [1.5, 2]})
assert place.tags == {"a", "b"} and place.point == (1.5, 2.0)
assert place.dump() == {"tags": ["a", "b"], "point": [1.5, 2.0], "path": []}
try:
Place.validate({"tags": [], "point": [1.5]})
except ValidationError as error:
assert [(d.path, d.code) for d in error.details] == [("point", "min_length")]
- Duplicates in a set collapse;
min_lengthandmax_lengthon a set or variadic tuple count the array as sent. A fixed tuple has its length from its type (at least 2 items/at most 2 items), each position is checked atpoint[0], andField(...)constraints are refused on it. - Hashable items. Set and frozenset items must be hashable: scalars, enums, or tuples and frozensets of those. A set of
Schema,list,dictorsetitems raisesRegistrationError; bareset,tuple[()]and a misplaced...do too. - Construction takes exactly the declared container (
Place(tags={"a"}, point=(1, 2))); a list for asetfield is refused. - Output.
dump(), responses and the JSON encoder write arrays, a set sorted when its items compare;to_dict()keeps theset,frozensetandtuple. - Models. A
Modelcolumn annotated with one of these is a JSON column holding an array; the model stores and reads lists, and onlySchemafields build sets and tuples. - Lanes. The native GIL-free CRUD lane does not read these fields; such a schema is validated through the Python lane, with the same results.
- OpenAPI documents a set as an array with
uniqueItems, a variadic tuple as an array and a fixed tuple withprefixItems,minItemsandmaxItems.
Enums and literals¶
An Enum, StrEnum or IntEnum class, or a Literal of strings or of integers, accepts only the listed values. On the wire the value is the member's value; validation returns the member itself:
import enum
from typing import Literal
from hinoki import Schema
from hinoki.errors import ValidationError
class Status(enum.StrEnum):
DRAFT = "draft"
PUBLISHED = "published"
class Priority(enum.IntEnum):
LOW = 1
HIGH = 3
class Ticket(Schema):
channel: Literal["web", "email"]
status: Status = Status.DRAFT
priority: Priority = Priority.LOW
retries: Literal[0, 1, 3] = 0
ticket = Ticket.validate({"channel": "web", "status": "published", "priority": 3})
assert ticket.status is Status.PUBLISHED and ticket.priority is Priority.HIGH
assert ticket.dump() == {
"channel": "web",
"status": "published",
"priority": 3,
"retries": 0,
}
try:
Ticket.validate({"channel": "sms", "priority": 2})
except ValidationError as error:
assert [(d.path, d.code) for d in error.details] == [
("channel", "one_of"),
("priority", "one_of"),
]
- Values, not names. The names of the members never appear on the wire; the error message lists the accepted values (
must be one of 'web', 'email'). Matching is strict:"3"and3.0are not3, andTrueis not1. Wrong types answertype, a value outside the list answersone_of. - One kind of value. All values are
str, or all areint(64-bit, neverbool). A mixedEnumorLiteral,Noneinside aLiteral(writeLiteral["a"] | None), aFlagenum, an enum without members, an enum member inside aLiteral(use the class) and values of any other type raiseRegistrationError. Aliases of a member count once.Field(...)constraints, includingone_of, are refused on these fields: the type is the list. - Construction takes members for an enum field (
Ticket(status=Status.DRAFT)) and the listed values for aLiteral; a plain"draft"is refused for an enum field.validateand the request sources read the value, and a member of aStrEnumis read as its text. - Output.
dump(), responses and the JSON encoder write the member's value (insideSchemainstances);to_dict()keeps the member. - Text sources. Form, query and XML values are text; an
IntEnumor anintLiteralreads its number like anintfield does. - Models. A
Modelcolumn annotated with an enum or aLiteralstays a JSON column; onlySchemafields check the values. - OpenAPI documents the field as its
type(stringorinteger) with anenumlist of the values, inline in the property.
Dates, durations, decimals and bytes¶
date, time, timedelta, Decimal and bytes travel as JSON strings and are validated identically by the Python and the Rust lane:
import datetime as dt
from decimal import Decimal
from typing import Annotated
from hinoki import Field, Schema
class Booking(Schema):
day: dt.date
opens: dt.time
length: dt.timedelta
price: Annotated[Decimal, Field(ge=0, max_digits=8, decimal_places=2)]
receipt: Annotated[bytes, Field(max_length=1024)]
booking = Booking.validate(
{
"day": "2026-03-14",
"opens": "09:30:00+01:00",
"length": "PT1H30M",
"price": "19.90",
"receipt": "aGVsbG8=",
}
)
assert booking.length == dt.timedelta(hours=1, minutes=30)
assert booking.price == Decimal("19.90")
assert booking.receipt == b"hello"
assert booking.dump()["price"] == "19.90"
| Type | Accepted input | Output | Error code |
|---|---|---|---|
date |
YYYY-MM-DD, a real calendar date in years 0001–9999, ASCII digits |
the same text | date |
time |
HH:MM:SS[.f…f] with 1 to 6 fraction digits and a Z or ±HH:MM offset |
isoformat() |
time; time_tz when the offset is missing |
timedelta |
ISO 8601 [-]P[nD][T[nH][nM][n[.f…f]S]]; years, months and weeks are refused |
PT1H30M, P1DT2S, -PT0.5S |
duration; duration_range outside timedelta's range |
Decimal |
a string -?(0\|[1-9][0-9]*)(\.[0-9]+)? or an integer; floats, booleans, exponents, NaN and infinities are refused |
a fixed-point string that keeps the scale ("0.10") |
decimal |
bytes |
standard padded base64 (+, /, =); no whitespace or URL-safe alphabet |
padded base64 | bytes |
- A time needs an offset on the wire, as a
datetimedoes; a time without one is reported astime_tz. Fields derived from aModelthroughfrom_model()accept naive times, as they accept naive datetimes. Adatefield refuses adatetime. Decimalis exact. Boundsge,le,gtandlt(anintorDecimal, never a float) compare exactly.max_digits(default 64, at most 1000) counts all digits,decimal_placesthe digits after the point, and whendecimal_placesis declared the digits before the point are limited tomax_digits - decimal_places. The codes aremax_digits,decimal_placesandmax_whole_digits; the checks run in that order, then the bounds, thenmultiple_of. Adecimal_placesabovemax_digitsis refused at class creation.
Multiples¶
Field(multiple_of=step) requires an int or Decimal value to be a whole multiple of step. The step is a positive int (for int fields) or a positive finite int/Decimal (for Decimal fields) and the check is exact, however large the numbers. It runs after the bounds and fails with the code multiple_of. A float field refuses multiple_of at class creation because float multiples are inexact: declare a Decimal field instead.
from decimal import Decimal
from typing import Annotated
from hinoki import Field, Schema
class Order(Schema):
quantity: Annotated[int, Field(ge=0, multiple_of=5)]
price: Annotated[Decimal, Field(multiple_of=Decimal("0.05"), max_digits=8)]
Order.validate({"quantity": 10, "price": "9.95"}) # accepted
Order.validate({"quantity": 12, "price": "9.97"}) # two `multiple_of` errors
JSON input is already strict about types (a float is never an integer, a Decimal is a string); the text sources (query, form) coerce as documented above. A float field always holds a float: wire data gives 1.0 for the JSON number 1, and building a Schema in Python stores an int given for a float field, or for a float inside a list, set, tuple or dict[str, float], as a float (Reading(value=1).value is 1.0); a bool is still refused. A float member of a plain union such as int | float keeps the value it was given.
* bytes size. min_length and max_length count decoded bytes (at most 1024 bytes). Client input without a max_length is limited to 65536 decoded bytes (hinoki.fieldtypes.MAX_BYTES_LENGTH); a declared max_length replaces the limit. Fields derived from a Model column never get it. pattern is matched against the whole decoded value read as Latin-1 text, one character per byte, after the length check: Field(pattern=r"\x89PNG[\x00-\xff]*") accepts a PNG header, and a failure answers pattern. Both lanes and direct construction agree.
* Text sources. Form, query and XML values use the same text forms, so validate_text needs no conversion for these types.
* Models. A bytes column stores as BYTEA on PostgreSQL and a blob on SQLite, and native CRUD serialises it as base64. Constraints on a bytes model column are refused. The ORM stores only bytes among these types; date, time, timedelta and Decimal are not model column types yet.
* OpenAPI documents date as format: date, time as format: time, timedelta as format: duration, Decimal as a string with format: decimal and a pattern, and bytes as format: byte with contentEncoding: base64; the pattern of a bytes field is not described, because it applies to the decoded bytes and not to the base64 text. Decimal bounds appear as minimum/maximum numbers.
* Output. The JSON encoder writes these values only inside Schema instances; a bare Decimal or bytes in a plain dictionary is still a TypeError, so a handler that returns one must return a Schema or supply a default= hook. A Decimal that is NaN, infinite or has more than 1000 digits raises ValueError.
Dictionary fields¶
Use dict[str, X] for an object whose keys the client chooses, such as labels, per-locale texts or settings by name:
from typing import Annotated
from hinoki import Field, Schema
class Point(Schema):
x: int
y: int = 0
Locale = Annotated[
str, Field(min_length=2, max_length=5, pattern=r"[a-z]{2}(-[A-Z]{2})?")
]
class Place(Schema):
labels: Annotated[
dict[str, Annotated[str, Field(max_length=40)]], Field(max_length=20)
]
names: dict[Locale, Annotated[str, Field(max_length=80)]] = Field(
default_factory=dict
)
points: dict[str, Point] = Field(default_factory=dict)
place = Place.validate({"labels": {"kind": "park"}, "points": {"gate": {"x": 1}}})
assert place.points == {"gate": Point(x=1)}
assert place.dump() == {
"labels": {"kind": "park"},
"names": {},
"points": {"gate": {"x": 1, "y": 0}},
}
- Keys are strings.
dict[int, X],dict[UUID, X]and a baredictare refused at class creation with a message that namesdict[str, X]. Every key is an ordinary string:"__proto__"or"constructor"has no special meaning. - Values follow the value type, with its own
Field(...)constraints, nestedSchemas, lists, unions andNonewhen the value type allows it. A wholedict[...] | Nonefield acceptsnull. - Error paths add the key as one more dotted segment, as list items add
[index]:labels.kind,points.gate.x,scores.math[1]. A key longer than 64 characters is shortened to its first 64 in the path, as unknown field names are. The codes and messages are those of the value type. - Entry count.
Field(min_length=..., max_length=...)on the dict counts entries, exactly like a list:at least 1 item,at most 20 items. Amin_lengthabove the maximum in force is refused at class creation. - Key constraints. Annotate the key type to constrain keys:
dict[Annotated[str, Field(...)], X]acceptsmin_length,max_length,patternandformat=. A key that breaks one of these is reported once at its path withkey_min_length,key_max_lengthorkey_pattern(for examplekey must have at most 5 characters), and its value is not checked. A key that is not valid Unicode text (a lone surrogate in a Python string) is reported astypeat the field path. - Client input is always bounded. On wire input (
Schema.validate(...)and request bodies), a dict withoutmax_lengthaccepts at most 1000 entries (hinoki.fieldtypes.MAX_MAPPING_ITEMS) and a key without its ownmax_lengthat most 256 characters (hinoki.fieldtypes.MAX_MAPPING_KEY_LENGTH). A declaredmax_lengthreplaces these bounds. They do not apply to values the server builds: direct construction,from_model()and response projections accept larger stored dicts, and fields derived from a model column never get them. Declared limits apply everywhere. - Order and duplicates. Entries keep the order the client sent through
validate(),dump(),to_dict()and the JSON response. A key repeated in a JSON body behaves as in any JSON object: the last value wins and the key keeps its first position. - Construction.
Place(points={"gate": Point(x=1)})validates the dict like any field; a nested value must already be aSchemainstance and a non-string key is reported asobject keys must be strings.@field_checkand@object_checkof nested values run with the same key paths.from_model()copies a row's dict, as it copies lists. - OpenAPI describes the field as
type: objectwithadditionalPropertiesset to the value schema,propertyNamesset to the key schema andminProperties/maxPropertiesfrom declared entry limits. The wire-input bounds above are not written into the document, because the same component also describes responses, which they do not limit.
A text value without a limit is reported by the HNK-SCH-002 rule like a text field (see rules). HNK-SCH-001 (Schemas.forbid_exposure) checks field names only: the keys of a dict are runtime data, so a forbidden name used as a key is not detected. A Model column that holds a dict, directly or in list items, stays a JSON column: model writes do not apply these checks, and constraints on such a column are refused. A Schema derived from that model gets a dict[str, X] field validated as described here, without the wire-input bounds.
Checks of Schema values run through lists and dicts at any depth. A list[list[Point]] field runs Point's @field_check and @object_check for each inner item (rows[1][0].x); earlier versions skipped the checks of lists nested in lists.
Plain unions and Any¶
A union of ordinary types, such as int | str, accepts a value that fits any variant; Any and object accept every JSON value unchanged:
from typing import Annotated, Any
from hinoki import Field, Schema
from hinoki.errors import ValidationError
class Reading(Schema):
value: int | str
when: Annotated[int, Field(ge=0)] | Annotated[str, Field(max_length=10)]
extra: Any = None
reading = Reading.validate({"value": "abc", "when": 5, "extra": {"k": [1, None]}})
assert reading.value == "abc" and reading.when == 5
assert reading.dump() == {"value": "abc", "when": 5, "extra": {"k": [1, None]}}
try:
Reading.validate({"value": 1.5, "when": -1})
except ValidationError as error:
assert [(d.path, d.code) for d in error.details] == [
("value", "union"),
("when", "union"),
]
- First match wins. Variants are tried in declared order and the first that accepts the value is used; no variant is tried after it.
boolis never anintor a number, soint | strrefusestrue. A value no variant accepts is reported once at the field path with codeunionanddoes not match any allowed type, without the individual variant errors. - Limits. A union has 2 to 16 variants.
Field(...)constraints go on a variant (Annotated[str, Field(max_length=10)] | int), not on the union itself, and are refused there. A union made only ofSchemaclasses still needsField(discriminator=...)(see discriminated unions); a discriminated union can be one variant of a plain union. Anyandobjectaccept anything,nullincluded, and are returned as sent: no normalisation, no constraints. Use them for payloads the service stores or forwards without reading, and bound their size at the server or with aField(max_length=...)on the surrounding field.- Form, query and XML text. A text source has no types, so a union takes the first
int,floatorboolvariant that parses the text and otherwise keeps the text when astrvariant exists: forint | str,"5"becomes5and"abc"stays"abc". Lists from repeated keys stay lists of text, and a union with a list, tuple, dict orSchemavariant gets its text as sent, without conversion. - Bounded work. Nested unions are tried variant by variant, so a hostile payload could multiply the work; a request whose failed container trials inside one union exceed 1024 is refused with a validation error.
- Construction (
Reading(value=1, when="x")) takes a value of a variant's Python type; the first variant that takes that type is used, so adateis never turned into text by an earlierstrvariant. - Native lane. Plain unions and
Anyare checked in Rust on the Python-object path (Schema.validate, handlers on the native lane). ASchemathat uses one is not lowered to the GIL-free JSON lane, as with tuples; the results are identical. - OpenAPI describes a plain union as
anyOfof the variant schemas andAnyas an unconstrained schema. AModelcolumn annotated with a plain union orAnystays a JSON column. HNK-SCH-002checks each text variant of a union formax_length.
TypedDict and dataclass fields¶
A field may be annotated with a TypedDict or a dataclass. It is validated as a nested object and described in OpenAPI as a component named after the type.
class Address(TypedDict):
street: str
zip: NotRequired[str]
@dataclass
class Geo:
lat: float
lon: float = 0.0
class Place(Schema):
address: Address
geo: Geo | None = None
- The value is a generated
Schema. Hinoki builds oneSchemaper type, with the same name and fields, and the validated value is an instance of it:place.address.streetworks, but the value is not adictor aGeo.dump()gives the JSON form. Methods,__post_init__and base classes of the original type are not carried over. - Required keys. A
TypedDictkey that may be missing (NotRequired, or any key of atotal=Falseclass unlessRequired) becomes| Unset: a key the client left out staysUNSETand is left out ofdump(). A dataclass field with a default or adefault_factoryis optional. - Constraints.
Annotated[..., Field(...)]on a member of the type is honoured; constraints on the field that holds the whole type are refused, as for a nestedSchema. - Limits. A dataclass field with
init=Falseand a recursive type raiseRegistrationError. - Native lane. The generated class is an ordinary
Schema, so both lanes validate it the same way.
Internet addresses, Email, Url and Slug¶
from ipaddress import IPv4Address, IPv4Network
from hinoki import Email, Schema, Url
from hinoki.errors import ValidationError
class Allowlist(Schema):
owner: Email
homepage: Url | None = None
source: IPv4Address
subnet: IPv4Network | None = None
rule = Allowlist.validate(
{"owner": "ops@example.com", "source": "10.0.0.7", "subnet": "10.0.0.0/24"}
)
assert rule.source == IPv4Address("10.0.0.7")
assert rule.dump()["subnet"] == "10.0.0.0/24"
try:
Allowlist.validate(
{"owner": "ops@example.com", "source": "10.0.0.7", "subnet": "10.0.0.7/24"}
)
except ValidationError as error:
assert [(d.path, d.code) for d in error.details] == [("subnet", "ipv4network")]
- Types.
IPv4Address,IPv6Address,IPv4NetworkandIPv6Networkfromipaddressare read from a JSON string and become the object. The error code isipv4,ipv6,ipv4networkoripv6network. A union such asIPv4Address | IPv6Addresstakes either family. - Strict text. Only ASCII is accepted. IPv4 refuses leading zeros; IPv6 refuses a zone id (
fe80::1%eth0). A network needs a prefix length of plain digits within its family (no netmask form, no sign) and no host bits set (10.0.0.7/24is refused); a bare address is a single-host network. - No constraints.
Field(...)options do not apply to these types and are refused when the class is created. Output is the canonical text (dump()and JSON responses); constructing withAllowlist(source=...)takes the matchingipaddressobject only. Email,UrlandSlugareAnnotated[str, Field(format=...)]shortcuts (see validation). They are plain text, so they also work asModelcolumns.Emailis a syntactic check, not a deliverability check.- OpenAPI writes
type: stringwithformat: ipv4,ipv6,ipv4networkoripv6network. - Native lane. Checked in Rust on both lanes with the same grammar; the GIL-free lane keeps the text and builds the
ipaddressobject when a handler asks for it. - Models. A
Modelcolumn of these types is stored astextand read back as the object; a write checks that the value is anipaddressobject of the right family before SQL is sent (ModelValidationError). See models.
SecretStr and Path¶
from pathlib import Path
from hinoki import Field, Schema, SecretStr
from typing import Annotated
class Account(Schema):
password: Annotated[SecretStr, Field(min_length=8)]
home: Path
account = Account.validate({"password": "correct horse", "home": "/srv/ann"})
assert account.password.get_secret_value() == "correct horse"
assert repr(account.password) == "SecretStr('**********')"
assert account.dump() == {"password": "**********", "home": "/srv/ann"}
assert account.home == Path("/srv/ann")
SecretStrreads a JSON string and wraps it.repr,str,dump()and JSON responses show**********; onlyget_secret_value()returns the text. Validation errors never repeat the value.min_length,max_lengthandpatternapply. Constructing withAccount(password=...)takes aSecretStronly, so a plain string never ends up unmasked in an instance.Pathreads a non-empty JSON string without a NUL character and becomes apathlib.Path. Nothing touches the file system.min_lengthandmax_lengthapply; withoutmax_length, wire input is capped at 4096 characters. The error code ispath. Output isstr(path); constructing takes aPathobject only (aPurePathis refused).- OpenAPI writes
type: stringwithformat: path, and for a secretformat: passwordwithwriteOnly: true. - Lanes. Both are validated in Rust; a
Schemausing them is served by the Python lane, by design, because the GIL-free lane cannot build these objects. - Models. There is no
Modelcolumn for either type yet: generating a migration for one reportsno SQL type.
Documenting a field¶
Field(description=..., examples=..., deprecated=True) documents a field in the OpenAPI document without changing how it validates. description is non-empty text, examples a non-empty sequence of JSON values and deprecated marks the property as deprecated. The notes are written next to the property, so a nullable field is documented as a whole and a nested Schema keeps its $ref. They combine with constraints and with alias.
class Profile(Schema):
nick: Annotated[
str,
Field(max_length=20, description="Public handle.", examples=("ada", "grace")),
]
old_nick: Annotated[str | None, Field(deprecated=True)] = None
Computed fields¶
@computed_field adds a read-only value to the output of a Schema. The
method takes only self, needs a return annotation and is read as an
attribute:
from hinoki import Schema, computed_field
class Person(Schema):
first: str
last: str
@computed_field(alias="displayName", description="First and last name")
def full_name(self) -> str:
return f"{self.first} {self.last}"
person = Person(first="Ada", last="Lovelace")
person.full_name # "Ada Lovelace"
person.dump() # {"first": "Ada", "last": "Lovelace", "displayName": "Ada Lovelace"}
- Computed values follow the declared fields in
dump(), in HTTP responses (both the Rust JSON lane and the Python path) and in nested schemas.includeandexcludeaccept their names;exclude_unsetkeeps them.to_dict()leaves them out. - They are output only. A client that sends one gets the usual unknown-field
error, and
Person.validate(...)never reads them. - The OpenAPI document lists them as
readOnlyproperties, never asrequired, withdescriptionandexampleswhen given. - A computed field cannot reuse the name or the wire name of a field or of
another computed field (
RegistrationError). Subclasses inherit them. Person.computed_fields()returns the{name: spec}mapping.- A schema with computed fields is serialized through the schema instance, not the direct row-to-JSON shortcut.
Wire aliases¶
Use Field(alias=...) when the public JSON name should differ from the Python attribute. The alias is the only accepted input key; sending both names is an error. dump() writes aliases, including in nested schemas and lists, while to_dict() keeps Python attribute names. Validation errors and OpenAPI properties use the wire names. A custom check's default field path is translated to its alias; an explicit Invalid(path=...) is already a wire path.
from typing import Annotated
from hinoki import Field, Schema
class PersonOut(Schema):
first_name: Annotated[str, Field(alias="firstName")]
person = PersonOut.validate({"firstName": "Aki"})
assert person.first_name == "Aki"
assert person.dump() == {"firstName": "Aki"}
assert person.to_dict() == {"first_name": "Aki"}
An assigned declaration such as display_name: str = Field(alias="displayName") is also supported, including alongside default_factory. Aliases must be unique within a schema and cannot contain ., [ or ], which are reserved by error paths. Model columns do not accept wire aliases; put API naming on the Schema.
Class configuration¶
SchemaConfig is an immutable typed configuration passed in the class declaration. By default, unknown string keys in decoded input are rejected. SchemaExtra.IGNORE discards them while keeping declared fields strict:
from hinoki import Schema, SchemaConfig, SchemaExtra
class VendorEvent(Schema, config=SchemaConfig(extra=SchemaExtra.IGNORE)):
event_id: str
revision: int
event = VendorEvent.validate(
{"event_id": "evt-1", "revision": 2, "vendor_context": {"trace": "abc"}}
)
assert event.dump() == {"event_id": "evt-1", "revision": 2}
Ignored values are not stored as attributes or emitted by dump(). A wrong type, failed constraint or missing required field among the declared fields still raises ValidationError before either a sync or async handler runs. This option applies to decoded Schema.validate(...) input and request bodies. Generated constructor keywords and explicit from_model(..., **extra) overrides keep their normal strict signatures. Each nested Schema uses its own configuration.
An alias remains the only accepted wire name. If given_name has alias givenName, sending only given_name is ignored as an extra and the required givenName field remains missing; sending both names is still a duplicate-field error. OpenAPI marks an IGNORE schema with additionalProperties: true, while its response serialization still includes only declared fields.
Schema(...) validates the final Python values immediately and raises ValidationError for invalid values. Pass Python objects such as UUID, timezone-aware datetime and nested Schema instances. Schema.validate(decoded_data) is the wire-input path: it accepts JSON-compatible values, resolves aliases and returns field errors using wire names. Request body binding uses that path before calling the handler. from_model() also validates the constructed Schema; naive datetimes returned by database drivers remain unchanged and are allowed on that model-conversion path. When a handler declares one concrete Schema return type, a direct Model result is passed through from_model() automatically (an invalid row is a 500, not a 422) and a subclass instance is sent with the declared fields only; this does not validate other handler return values such as a dict. See Schemas derived from models.
Generic schemas¶
Declare type parameters with the Python 3.12 syntax and parameterize the class where it is used. Envelope[User] is a real, cached Schema subclass: it validates on both lanes, appears in the OpenAPI document as its own component (Envelope_User_) and keeps Field(...) metadata, defaults, checks and computed fields.
from hinoki import Schema, http
class User(Schema):
name: str
class Envelope[T](Schema):
data: T
count: int = 0
@http.get("/user")
async def show(request) -> Envelope[User]:
return Envelope[User](data=User(name="Ada"))
Limits: the unparameterized Envelope cannot validate or be used as a field (RegistrationError); the argument count must match; a schema that refers to itself (children: list[Tree[T]]) is refused as recursive; and a generic subclass of a generic schema (class Child[T](Base[T])) is not supported: the base class's fields keep the type variable and parameterizing the child fails with a RegistrationError.
Discriminated unions¶
Use a discriminated union when one field can contain one of several known Schema shapes. Declare the union on a Schema field with Annotated[Cat | Dog, Field(discriminator="kind")]. Every variant needs the same required string field, the same wire alias for that field, and exactly one Field(one_of=(...)) tag. Hinoki selects the variant by that tag in Rust; it does not try each schema in order.
from typing import Annotated
from hinoki import Field, Schema, http
class Cat(Schema):
kind: Annotated[str, Field(alias="type", one_of=("cat",))]
name: str
class Dog(Schema):
kind: Annotated[str, Field(alias="type", one_of=("dog",))]
walks: int
Pet = Annotated[Cat | Dog, Field(discriminator="kind")]
class PetRequest(Schema):
pet: Pet
@http.post("/pets")
async def create_pet(data: PetRequest) -> PetRequest:
return data
PetRequest.validate({"pet": {"type": "cat", "name": "Mugi"}}) returns a PetRequest whose pet is a Cat; manual construction takes an already validated variant instance, such as PetRequest(pet=Dog(kind="dog", walks=2)). A dict is not coerced into a variant. list[Pet], nested Schema fields, nullable unions and Unset use the same discriminator rules. Unknown tags produce a field error at the tag's wire path without echoing the submitted value. The handler is not called for an invalid body, whether it is synchronous or asynchronous.
Each variant's tag field is required and cannot have a default. Tags must be unique strings, variants must be distinct Schema classes, and variant classes cannot override dump() because the override could remove or change the tag on the wire. Plain unions without Field(discriminator=...), non-Schema variants, and unions directly in handler body or return annotations are not supported; wrap the union in a Schema for route input and output. The runtime check of return values is separate and applies to every action.
Changing a value¶
A Schema instance is frozen. replace(**changes) returns a copy with the named fields changed; the original is untouched. Every value of the copy goes through the same validation, normalisation and @field_check/@object_check as a new instance, so a change that breaks a rule raises ValidationError with the field path, and a check sees the whole new object. An unknown field name raises TypeError. Fields that were never supplied stay unsupplied for dump(exclude_unset=True), and replace is reserved as a Schema method name, like dump.
card = Card(title="Draft", stars=1)
published = card.replace(title="Final", stars=4)
assert card.stars == 1 and published.stars == 4
Projection options on dump()¶
Use dump() when application code needs a JSON-compatible projection of a Schema. include and exclude accept Python field names and apply to the top-level fields only; exclusion wins if a field appears in both. There are no dotted paths or nested selection maps. Nested Schemas and supported lists are converted recursively, with by_alias applied at every Schema level.
from typing import Annotated
from hinoki import Field, Schema
class PersonOut(Schema):
first_name: Annotated[str, Field(alias="firstName")]
bio: str = ""
person = PersonOut.validate({"firstName": "Aki"})
assert person.dump() == {"firstName": "Aki", "bio": ""}
assert person.dump(exclude_unset=True) == {"firstName": "Aki"}
assert person.dump(include={"first_name"}, by_alias=False) == {"first_name": "Aki"}
assert person.dump(include=set()) == {}
exclude_unset=True omits values supplied by dataclass defaults or default factories when the caller did not provide that field. It does not compare values with defaults: explicitly passing bio="", None, 0, False or an empty collection keeps that value. UNSET is omitted regardless of this option. from_model() tracks attributes it actually reads and values passed via **extra; missing optional attributes that use Schema defaults remain unset. A custom __post_init__ changing a field does not make it supplied. A custom __init__ has no reliable input-presence information, so exclude_unset=True raises TypeError for its instances.
With no options, dump() preserves its current output and honors custom dump() overrides, including nested ones. Root-only include and exclude can select a custom-dumped nested value; recursive controls (exclude_unset=True or by_alias=False) refuse that value because Hinoki cannot safely inspect the override. A zero-argument override continues to work at runtime for automatic HTTP output, but widening the base signature means mypy flags that override; typed overrides that use the new options must accept the same keyword-only signature. Filtering a manually returned dictionary does not change the OpenAPI contract and is not an authorization mechanism; declare a response Schema containing only fields the caller may see. to_dict() remains the Python-value conversion and its existing exclude= behavior is unchanged.
dump is reserved as a Schema method name. Declaring a field with that Python attribute name raises RegistrationError instead of treating the inherited method as a default value; rename the Python field to avoid the collision. A wire alias alone cannot resolve a Python attribute-name conflict.
Built-in and custom validation¶
Field(...) provides built-in structural constraints. format= accepts email, url, slug or hex_color and is shorthand for a regular-expression pattern. Numeric bounds apply to numbers; length limits apply to strings and collections; one_of restricts a value to the listed choices.
Field(strip=True), Field(lower=True) and Field(upper=True) normalise a str field before anything else is checked, so min_length, pattern and one_of see the normalised text and the value you read is the normalised one:
class Signup(Schema):
handle: Annotated[str, Field(strip=True, lower=True, min_length=3)]
Signup.validate({"handle": " AbC "}).handle # "abc"
- Same on both lanes. The Python-object path, the native JSON path and direct construction (
Signup(handle=" ABC ")) give the same result.stripremoves what Python'sstr.strip()removes, including U+001C to U+001F;lowerandupperuse the Unicode case mapping ofstr.lower()andstr.upper(). - Before
@field_normalize. A custom normalizer receives the already normalised text. - Limits. Only
strfields accept them (notbytes,SecretStr,Pathor aLiteral);loweranduppercannot both be set; aone_ofvalue that the normalisation would change (upper=Truewithone_of=("ab",)) raisesRegistrationError. The OpenAPI document describes the constraints that apply to the normalised value and has no keyword for the normalisation itself.
from typing import Annotated
from hinoki import (
Field,
Invalid,
Schema,
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",
)
Structural validation runs first and rejects wrong types, missing required values, unknown keys and failed constraints. @field_normalize("email") then receives a valid string and returns its canonical form; the result is checked against the same Field(...) constraints before it is applied. The same hook runs for Schema.validate(...), direct Schema(...) construction and from_model(...). It cannot rescue an input that failed the initial validation. Normalizers must be typed synchronous methods returning str; they cannot perform I/O or reject input.
After normalization, field checks receive final values and object checks can compare final fields. Raise Invalid(code, message) to reject a value; these checks return None and do not transform it. Non-None returns and async check methods are programming errors. Applicable custom-check failures are returned together in errors.ValidationError.details. Checks must be side-effect free; do not query the database or call external services. Put checks that depend on current data in an operation.
Which lane runs what. Types and Field(...) constraints are checked in Rust, on the Python-object path and, for most schemas, the GIL-free JSON path. The three decorators are Python callables, so they run in Python: Rust validates the structure first, and the normalizers, field checks and object checks run only on values that passed it. Computed fields are not available yet.
These decorators validate a Schema instance passed through Schema.validate; they are not run on a Model. Model fields have separate checks that run before ORM writes, described in Model field constraints and validators.
Reshaping input with @before_validate¶
@before_validate marks a classmethod or staticmethod that receives the decoded request mapping and returns the mapping to validate. Use it to accept an older or looser input shape, such as a renamed key (unknown keys are refused, so the hook drops the old one), and still get the full structural validation afterwards.
from typing import Any
from hinoki import Schema, before_validate
class Profile(Schema):
display_name: str
@before_validate
@classmethod
def accept_legacy_name(cls, data: dict[str, Any]) -> dict[str, Any]:
if "name" in data and "display_name" not in data:
rest = {key: value for key, value in data.items() if key != "name"}
return {**rest, "display_name": data["name"]}
return data
assert Profile.validate({"name": "Ada"}).display_name == "Ada"
- Where it runs. On the schema and on every schema nested in it (lists, dicts, tuples, optionals and discriminated variants), before any structural validation, on the Python and the Rust lane alike. Base-class hooks run before a subclass's.
- Untrusted input. The hook sees data that has not been checked: test types before using them. It gets a shallow copy of the mapping, so replace nested values instead of mutating them. It must be synchronous and do no I/O.
- Refusing. Raise
Invalid(code, message)to answer 422. AKeyError,TypeError,ValueError,IndexErrororAttributeErrorcaused by unexpected input answersinvalid_inputrather than 500. - Limits. A plain union of schemas where a member has such a hook is refused at class creation: use a discriminated union. The decorator on a plain method raises
RegistrationError.
Text that cannot be stored¶
A string value or a dict key that contains a NUL character (\u0000) is refused with the code nul, or key_nul for a dict key, on both lanes. PostgreSQL cannot store NUL in text, so the request answers 422 instead of failing later with a server error. The check runs after the length limits and before pattern. A Python string that is not valid Unicode (a lone surrogate such as "\ud800") is refused with the code type, because it cannot be encoded as UTF-8.
See also the glossary for what "schema" does and does not mean in these docs.