annotated
Validation for structs and enums that works with serde. You write rules on a struct's fields. When the struct is deserialized, you get every problem back in one error: broken rules and missing fields together, each with the path of the field it belongs to. If you would rather stop at the first problem, the _fail_fast functions do that.
use ;
- Every problem at once. A client fixing a request sees everything that is wrong with it in one response, instead of one field per round trip.
- Field names as serde reads them. The example reports
fullName, notfull_name, because of itsrename_all. - Issues are data. Each one has a path, a stable code, typed parameters and an English message you can replace.
- Nothing to pay for valid input. Validating a valid value allocates nothing.
- Any serde format. JSON has ready-made functions, and every other format works through its
Deserializer.
Status: 0.2. Until 1.0, a release may change the API. When one does, the changelog says what changed.
Getting started
[]
= { = "0.1", = ["json"] }
annotated is the only crate to add. It re-exports its derive macros, and the code they generate doesn't need serde among your dependencies.
- Derive
annotated::Deserializewhere you would deriveserde::Deserialize. - Write each field's rules in
#[validate(...)]. - Deserialize with
annotated::json::from_str, and read the issues from the error.
To check a value that already exists, derive annotated::Validate and call value.validate(). It works on its own or beside Deserialize, from the same #[validate(...)] rules.
Where it fits
validator and garde check a struct after serde has built it. If a field is missing or has the wrong type, serde stops at that first error, and no rule ever runs.
annotated validates while it deserializes, so a missing field is one more issue instead of the end of deserialization. The struct still implements serde::Deserialize, so it works anywhere serde does.
Rules
| Rule | The value passes when |
|---|---|
required |
It is present: an Option is Some, a string isn't empty or only whitespace, a collection isn't empty |
length(min = 1, max = 50) |
Its length is within the bounds, or exactly length(equal = 5). A string is counted in chars, or in bytes or graphemes with unit = "bytes" or unit = "graphemes". A collection is counted in elements |
range(min = 18, max = 120) |
It is within the bounds, both included |
email |
It is an email address, as HTML's <input type="email"> accepts one, of at most 254 bytes |
url |
It is an absolute URL with a host and no userinfo (user@), using http, https or ftp. url(schemes = &["https"]) accepts other schemes instead |
ip, ipv4, ipv6 |
It is an IP address: of either version, only version 4, or only version 6 |
contains = "@", prefix = "SKU-", suffix = ".pdf" |
The string contains, starts with or ends with the text |
pattern = r"^\d{5}$" |
The string matches the regular expression, anywhere in it unless the expression is anchored with ^ and $. Needs the regex feature |
custom(function) |
Your function, any Fn(&T) -> Result<(), Problem>, returns Ok(()) |
nested |
The field is a struct or an enum with rules of its own, and it passes them |
each(...) |
Every element of the collection, or every value of the map, passes the rules inside: each(length(max = 20)), each(nested) |
- Order. A field's rules run in the order written, and the field stops at its first broken rule. So a blank name isn't also reported as too short. Put
#[validate(report_all)]on the struct to report every broken rule instead. Optionfields.requiredchecks that the field isSome. Every other rule checks the value inside, and is skipped when the field isNone.- Messages. Give a rule
message = "..."to replace its English message.{param}placeholders are filled from the problem's parameters:length(max = 50, message = "use {max} characters or fewer"). - Rules across fields.
#[validate(custom(function))]on the struct checks the whole struct, after its fields, with anyFn(&Self) -> Result<(), Problem>.custom(function, field = repeated_password)reports the problem at that field. - Enums. Rules go on the fields of an enum's variants, named or not. The variant the value holds is checked, and each issue is at the path where serde reads its value, such as
card.numberunder the variant's name. - Rules of your own. Besides
custom, a rule can be a type of yours that implementsRule. Write it by its path, with the same syntax as the built-in rules:my_rules::iban(country = "ES"). - No I/O. A rule looks at the value and nothing else. A check that needs I/O, like "is this email already taken", belongs in your application, after validation.
Reading the issues
The error holds its issues in the order of the struct's fields, followed by those of struct-level rules. Each Issue gives you:
| Call | What you get | For the age in the example |
|---|---|---|
path() |
Where the problem is. to_string() gives a dotted path, and json_pointer() an RFC 6901 JSON Pointer |
age and /age. Deeper in a value, members[1].name and /members/1/name |
problem().code() |
A stable code, for code that translates the problem or reacts to it | range |
problem().params() |
The rule's parameters, as numbers or text | min is 18 and max is 120 |
message() |
A message for people: the rule's message when it has one, or else the English one |
must be between 18 and 120 |
Printed, the error is one issue per line: age: must be between 18 and 120.
Ways to validate
| You call | For input that breaks the rules, you get |
|---|---|
annotated::json::from_str or from_slice, with the json feature |
A DeserializeError holding the issues as data, as in the example |
annotated::from_deserializer, with any serde Deserializer |
The same |
serde_json::from_str, or anything else that goes through serde::Deserialize |
A serde error with every issue in its message. A serde error can only carry a message, not data |
value.validate(), on a struct that derives Validate |
Issues, for a value that already exists, whether or not serde built it |
To stop at the first issue, call from_str_fail_fast, from_slice_fail_fast, from_deserializer_fail_fast or validate_fail_fast instead. Each returns only the issue the full report would list first. Going through serde::Deserialize always collects every issue.
Values of the wrong type
A value of the wrong type, like "age": "twelve", ends deserialization with the format's own error, as it does with serde. Put #[annotated(collect_type_errors)] on the struct to get it as one more issue instead, with the code invalid_type and the message must be u8, found string. The issue names the kind of value found, never the value itself, so nothing a client sent is echoed back. This needs a self-describing format, such as JSON.
Features
| Feature | What it adds |
|---|---|
serde, on by default |
#[derive(Deserialize)] and annotated::from_deserializer |
json |
annotated::json, built on serde_json |
regex |
The pattern rule |
unicode |
length(unit = "graphemes") |
Web frameworks
There is no crate for any framework. examples/axum is an axum extractor to copy into your app instead. It responds with 422 and lists every issue as RFC 9457 problem details.
Learn more
- The API documentation describes every rule, type and option.
- The changelog lists what each release changed.
- ARCHITECTURE.md explains how the library is built, with the principles and terms it keeps.
Minimum supported Rust version
The three most recent stable releases are supported, so today the minimum is Rust 1.98. Raising the minimum is not a breaking change, and the changelog notes each time it happens.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.