# annotated
Validation for structs 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.
```rust
use annotated::{Deserialize, ParamValue, Path, Problem, Validate};
#[derive(Validate, Deserialize, Debug)]
#[serde(rename_all = "camelCase")]
struct NewMember {
#[validate(required, length(max = 50))]
full_name: String,
#[validate(email)]
email: String,
#[validate(range(min = 18, max = 120))]
age: u8,
}
#[test]
fn every_problem_with_a_new_member_is_reported_at_once() {
let body = r#"{ "fullName": " ", "age": 12 }"#;
let error = annotated::json::from_str::<NewMember>(body).unwrap_err();
let [blank_name, missing_email, too_young] = error.issues() else {
panic!("expected three issues, got {error:?}");
};
assert_eq!(blank_name.path(), &Path::root().field("fullName"));
assert_eq!(blank_name.problem(), &Problem::Required);
assert_eq!(missing_email.path(), &Path::root().field("email"));
assert_eq!(missing_email.problem(), &Problem::Missing);
assert_eq!(too_young.path(), &Path::root().field("age"));
assert_eq!(too_young.problem().code(), "range");
assert_eq!(
too_young.problem().params(),
[("min", ParamValue::Integer(18)), ("max", ParamValue::Integer(120))],
);
}
```
- **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`, not `full_name`, because of its `rename_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.1, the first release. Until 1.0, a release may change the API. When one does, the changelog says what changed.
## Getting started
```toml
[dependencies]
annotated = { version = "0.1", features = ["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.
1. Derive `annotated::Deserialize` where you would derive `serde::Deserialize`.
2. Write each field's rules in `#[validate(...)]`.
3. 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](https://crates.io/crates/validator) and [garde](https://crates.io/crates/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
| `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 `char`s, 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 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.
- **`Option` fields.** `required` checks that the field is `Some`. Every other rule checks the value inside, and is skipped when the field is `None`.
- **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 any `Fn(&Self) -> Result<(), Problem>`. `custom(function, field = repeated_password)` reports the problem at that field.
- **Rules of your own.** Besides `custom`, a rule can be a type of yours that implements `Rule`. 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:
| `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
| `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
| `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`](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](https://docs.rs/annotated) describes every rule, type and option.
- The [changelog](CHANGELOG.md) lists what each release changed.
- [ARCHITECTURE.md](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.97. 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](LICENSE-APACHE) or [MIT license](LICENSE-MIT) 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.