deserr

deserr is a Rust deserialization crate from the Meilisearch team, designed for user-facing APIs where the quality of error messages matters as much as the parsing itself. Unlike serde, deserr returns custom, type-specific errors on failure and offers better defaults for API-facing use cases.

A key design choice sets it apart: deserr does not parse the serialization format itself. Instead it offloads format parsing to crates like serde_json and then deserializes the already-parsed value into your final type, giving you full control over error codes and messages per field. It ships a derive macro plus ready-made integrations for actix-web and axum.

What You Get

• A Deserr trait and #[derive(Deserr)] macro for turning already-parsed values into typed structs.
• Customizable, type-specific error handling with control over error codes and messages per field.
• Framework integrations for actix-web and axum request extraction.
• Format-agnostic design that works with any parser producing an intermediate value (e.g. serde_json).
• A reference book, examples directory, and attribute-level integration tests.

Common Use Cases

• Validating and deserializing JSON request bodies in a web API with precise, user-facing error messages.
• Returning stable, customizable error codes for specific fields that fail validation.
• Extracting typed data from actix-web or axum handlers with deserr’s built-in integrations.
• Replacing serde in API layers where default error messages are too opaque to expose to clients.

Under The Hood

Architecture — deserr separates format parsing from deserialization: a caller parses bytes with a format crate (serde_json, etc.), then deserr walks the resulting intermediate value via its IntoValue/Value model (value.rs) and constructs the target type through the Deserr trait (lib.rs, impls.rs). Error construction is pluggable through dedicated error types in errors/ (json.rs, query_params.rs), and framework glue lives in src/actix_web and src/axum. A companion derive/ crate provides the #[derive(Deserr)] procedural macro.

Tech Stack — Rust with a workspace containing the core crate, a derive proc-macro crate, benches, examples, and an mdBook. Integrations are gated for actix-web and axum, and serde_json is used as the reference format parser. Dual-licensed MIT OR Apache-2.0.

Code Quality — Testing is thorough: tests/ holds many focused integration tests (each attribute and error message has a simple test), plus compiletest-based checks for the derive macro and inline unit tests in the error modules. The code is production-hardened — it powers Meilisearch’s API routes — and organized into clear modules per concern.

API Design — The public API is ergonomic for its target audience: derive Deserr on a struct, wire up an error type, and get typed extraction with tailored messages. The mental model (parse first, then deserialize) is slightly different from plain serde, but the reference book and per-attribute examples flatten the learning curve, and the actix/axum integrations remove boilerplate for web handlers.