Valico is a validation and coercion tool for JSON objects, written in Rust and inspired by [Grape]. It designed to be a support library for the various REST-like frameworks or other tools that need to validate and coerce JSON input from outside world.
It has built-in support for common coercers, validators and can return detailed error messages if something goes wrong.
```toml
[dependencies.valico] git = "https://github.com/rustless/valico" ```
See also:
All Valico stuff is making by Builder instance. Below is a simple example showing how one can create and setup Builder:
~~~rust let params = Builder::build(|params| { params.reqnested("user", Builder::list(), |params| { params.reqtyped("name", Builder::string()); params.reqtyped("friendids", Builder::list_of(Builder::u64())) }); }); ~~~
Later params instance can be used to process one or more JSON objects with it's process method with signature fn process(&self, tree: &mut JsonObject) -> ValicoResult<()>.
Note that Valico will mutate borrowed JSON value if some coercion is needed.
Example:
~~~rust
extern crate valico; extern crate serialize;
use serialize::json; use serialize::json::{ToJson}; use valico::{Builder, MutableJson};
fn main() {
let params = Builder::build(|params| {
params.req_nested("user", Builder::list(), |params| {
params.req_typed("name", Builder::string());
params.req_typed("friend_ids", Builder::list_of(Builder::u64()))
});
});
let mut obj = json::from_str(
r#"{"user": {"name": "Frodo", "friend_ids": ["1223"]}}"#
).unwrap();
match params.process(obj.as_object_mut().unwrap()) {
Ok(()) => {
println!("Result object is {}", obj.to_pretty_str());
},
Err(err) => {
panic!("Error during process: {}", err.to_json().to_pretty_str());
}
}
} ~~~
Also you can look to the [specs] for more details and examples.
You can define validations and coercion options for your parameters using a Builder::build block. Parameters can be optional and required. Requires parameters must be always present. Optional parameters can be omitted.
When parameter is present in JSON all validation and coercions will be applied and error fired if something goes wrong.
This functions are available in Builder to define parameters:
~~~rust
// Parameter is required, no coercion fn req_defined(&mut self, name: &str);
// Parameter is required, with coercion
fn req_typed(&mut self, name: &str, coercer: Box
// Parameter is required, with coercion and nested checks
fn reqnested(&mut self, name: &str, coercer: Box
// Parameter is required, setup with Param DSL fn req(&mut self, name: &str, param_builder: |&mut Param|);
// Parameter is optional, no coercion fn opt_defined(&mut self, name: &str);
// Parameter is optional, with coercion
fn opt_typed(&mut self, name: &str, coercer: Box
// Parameter is optional, with coercion and nested checks
fn optnested(&mut self, name: &str, coercer: Box
// Parameter is required, setup with Param DSL fn opt(&mut self, name: &str, param_builder: |&mut Param|);
~~~
Available list of coercers:
Example of usage:
~~~rust let params = Builder::build(|params| { params.reqtyped("id", Builder::u64()); params.reqtyped("name", Builder::string()); params.opttyped("isactive", Builder::boolean()); params.opttyped("tags", Builder::listof(Builder::strings())); }); ~~~
You can specify rules to nesting processing for lists and objects:
~~~rust let params = Builder::build(|params| { params.reqnested("user", Builder::object(), |params| { params.reqtyped("name", Builder::string()); params.opttyped("isactive", Builder::boolean()); params.opttyped("tags", Builder::listof(Builder::strings())); }); });
let params = Builder::build(|params| { params.reqnested("users", Builder::list(), |params| { params.reqtyped("name", Builder::string()); params.opttyped("isactive", Builder::boolean()); params.opttyped("tags", Builder::listof(Builder::strings())); }); }); ~~~
Nesting level is not limited in Valico.
You can use DSL block to setup parameters with more flexible way:
~~~rust let params = Builder::build(|params| { params.req("user", |user| { user.desc("Parameter is used to create new user"); user.coerce(Builder::object());
// this allows null to be a valid value
user.allow_null();
user.nest(|params| {
params.req_typed("name", Builder::string());
params.opt("kind", |kind| {
kind.coerce(Builder::string());
// optional parameters can have default values
kind.default("simeple_user".to_string())
});
});
});
}); ~~~
Parameter validations available only in DSL block.
Parameters can be restricted to a specific set of values with allow_values:
~~~rust let params = Builder::build(|params| { params.req("kind", |kind| { kind.coerce(Builder::string()); kind.allowvalues(["circle".tostring(), "square".to_string()]); }) }) ~~~
Some values can be rejected with reject_values:
~~~rust let params = Builder::build(|params| { params.req("userrole", |kind| { kind.coerce(Builder::string()); kind.rejectvalues(["admin".tostring(), "manager".tostring()]); }) }) ~~~
String values can be tested with Regex:
~~~rust let params = Builder::build(|params| { params.req("nickname", |a| { a.coerce(Builder::string());
// force all nicknames to start with "Amazing"
a.regex(regex!("^Amazing"));
})
}); ~~~
Sometimes it's usefull to use some custom function as validator:
~~~rust let params = Builder::build(|params| { params.req("pushkin_birthday", |a| { a.coerce(Builder::u64());
fn guess(val: &Json) -> Result<(), String> {
if *val == 1799u.to_json() {
Ok(())
} else {
Err("No!".to_string())
}
}
a.validate_with(guess);
});
}); ~~~
One can use custom validator. Docs in Progress.
Some validators can be specified in Builder DSL block to validate a set of parameters.
Parameters can be defined as mutually_exclusive, ensuring that they aren't present at the same time in a request.
~~~rust let params = Builder::build(|params| { params.optdefined("vodka"); params.optdefined("beer");
params.mutually_exclusive(["vodka", "beer"]);
}); ~~~
Parameters can be defined as mutually_exclusive, ensuring that they aren't present at the same time in a request.
~~~rust let params = Builder::build(|params| { params.optdefined("vodka"); params.optdefined("beer");
params.mutually_exclusive(["vodka", "beer"]);
}); ~~~
Multiple sets can be defined:
~~~rust let params = Builder::build(|params| { params.optdefined("vodka"); params.optdefined("beer"); params.mutually_exclusive(["vodka", "beer"]);
params.opt_defined("lard");
params.opt_defined("jamon");
params.mutually_exclusive(["lard", "jamon"]);
}); ~~~
Warning: Never define mutually exclusive sets with any required params. Two mutually exclusive required params will mean params are never valid. One required param mutually exclusive with an optional param will mean the latter is never valid.
Parameters can be defined as 'exactlyoneof', ensuring that exactly one parameter gets selected.
~~~rust let params = Builder::build(|params| { params.optdefined("vodka"); params.optdefined("beer"); params.exactlyoneof(["vodka", "beer"]); }); ~~~
Parameters can be defined as 'atleastone_of', ensuring that at least one parameter gets selected.
~~~rust let params = Builder::build(|params| { params.optdefined("vodka"); params.optdefined("beer"); params.optdefined("wine"); params.exactlyone_of(["vodka", "beer", "wine"]); }); ~~~
Sometimes it's usefull to use some custom function as validator:
~~~rust let params = Builder::build(|params| { params.reqdefined("monstername");
fn validate_params(_: &JsonObject) -> Result<(),String> {
Err("YOU SHALL NOT PASS".to_string())
}
params.validate_with(validate_params);
}); ~~~
One can use custom validator. Docs in Progress.