Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.
What is Valico?
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.
# Cargo.toml
[]
= "https://github.com/rustless/valico"
See also:
- Rustless - REST-like API micro-framework for Rust that use Valico.
- queryst - Rust query string parser with nesting support can be used together with Valico to provide simple and safe toolchain for parsing query strings.
Basic Usage
All Valico stuff is making by Builder instance. Below is a simple example showing how one can create and setup Builder:
let params = build;
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:
extern crate valico;
extern crate serialize;
use json;
use ;
use ;
Also you can look to the specs for more details and examples.
Validation and coercion
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.
Builder
This functions are available in Builder to define parameters:
// Parameter is required, no coercion
;
// Parameter is required, with coercion
;
// Parameter is required, with coercion and nested checks
;
// Parameter is required, setup with Param DSL
;
// Parameter is optional, no coercion
;
// Parameter is optional, with coercion
;
// Parameter is optional, with coercion and nested checks
;
// Parameter is required, setup with Param DSL
;
Built-in Coercers
Available list of coercers:
- Builder::i64()
- Builder::u64()
- Builder::f64()
- Builder::string()
- Builder::boolean()
- Builder::null()
- Builder::list()
- Builder::list_of()
- Builder::object()
Example of usage:
let params = build;
Nested processing
You can specify rules to nesting processing for lists and objects:
let params = build;
let params = build;
Nesting level is not limited in Valico.
Parameters DSL
You can use DSL block to setup parameters with more flexible way:
let params = build;
Parameter validations
Parameter validations available only in DSL block.
allow_values
Parameters can be restricted to a specific set of values with allow_values:
let params = build
reject_values
Some values can be rejected with reject_values:
let params = build
regex
String values can be tested with Regex:
let params = build;
validate_with
Sometimes it's usefull to use some custom function as validator:
let params = build;
validate
One can use custom validator. Docs in Progress.
Builder validations
Some validators can be specified in Builder DSL block to validate a set of parameters.
mutually_exclusive
Parameters can be defined as mutually_exclusive, ensuring that they aren't present at the same time in a request.
let params = build;
mutually_exclusive
Parameters can be defined as mutually_exclusive, ensuring that they aren't present at the same time in a request.
let params = build;
Multiple sets can be defined:
let params = build;
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.
exactly_one_of
Parameters can be defined as 'exactly_one_of', ensuring that exactly one parameter gets selected.
let params = build;
at_least_one_of
Parameters can be defined as 'at_least_one_of', ensuring that at least one parameter gets selected.
let params = build;
validate_with
Sometimes it's usefull to use some custom function as validator:
let params = build;
validate
One can use custom validator. Docs in Progress.