4.4 · Concepts
Own schemas and ORM: what it means for integrations¶
Hinoki has its own Schema and Model classes. It does not accept Pydantic models, SQLAlchemy models or Django models as request bodies, responses or tables. This page says why, what that costs when you bring existing libraries, and which extension points exist today. It describes what is implemented; it is not a plugin roadmap.
Why the framework owns them¶
- One declaration feeds every output. A
Schemaand aModelare read by request binding, response checking, OpenAPI, application MCP, the admin and rules. Those tools can only promise the same contract everywhere if they read the same classes. - The hot paths are native. Routing, selected request parsing and ORM execution run in Rust against Hinoki's own declarations, so they do not call back into a validation library or a foreign ORM per request.
- Rules need known structure. A rule such as "a response
Schemanever exposespassword_hash" is checkable because the schema is a Hinoki class that can be inspected, not arbitrary validation code.
What this costs¶
- A library that expects its own model type does not plug in directly: a Pydantic-based client SDK, a SQLAlchemy extension or a Django app that needs a Django
Modelcannot be passed a HinokiModelorSchema. - There is no adapter that converts SQLAlchemy, Django or Pydantic models into Hinoki ones, and no package registry or plugin system.
- Supported databases are SQLite, PostgreSQL, MySQL and MariaDB through Hinoki's own drivers. Your existing ORM session or connection is not shared with Hinoki's pool.
Using other libraries anyway¶
Anything that works on plain Python data works with Hinoki. Schema.to_dict() and Schema.dump() give plain dictionaries, and a Schema is built from plain values, so the boundary with another library is ordinary Python:
from hinoki import Schema, http
class Quote(Schema):
symbol: str
price: float
@http.get("/quotes/{symbol}")
async def quote(symbol: str) -> Quote:
raw = await pricing_client.fetch(symbol) # any library, returning plain data
return Quote(symbol=raw["symbol"], price=raw["price"])
Keep the translation at the edge of the handler and keep your own database access (for a second store, for example) in a module so its lifetime follows the worker. Hinoki does not protect or time-box what that code does.
Extension points that exist¶
| You want to | Use | Guide |
|---|---|---|
| Add an authentication scheme | Subclass BearerAuth, APIKeyAuth or HeaderAuth |
Authentication |
| Reuse a permission rule | A typed Access policy |
Authentication |
| Accept or answer another body format | A parser or renderer | Parsers and renderers |
| Translate a library's exception | app.error_handler(Kind) |
Errors |
| Own a resource per worker | A module with ctx.provide and ctx.get, or a subclass that replaces DatabaseModule |
Modules |
| Enforce a team convention | Subclass hinoki.rules.Rule |
Rules |
| Add typed configuration | settings.AppSettings |
Settings |
| Add routes from a package | Anything include accepts: an API class, a function, a RouteGroup, a Mount or an object with an api() method |
Endpoints |
| Expose actions to an agent | expose_as_mcp with an explicit allowlist |
Application MCP |
| Add metrics, tracing or other cross-cutting behavior | Wrap the ASGI application | Serving |
| Run where only WSGI is available | WSGIAdapter |
Serving |
There is no middleware API of Hinoki's own: cross-cutting behavior outside a request's declared access, errors and transactions belongs in an ASGI wrapper, which sees the request before and after Hinoki. Hinoki also has no documented way to host another web application inside it; put the other service beside it behind a reverse proxy, or dispatch by path in your own ASGI code.