- Notifications
You must be signed in to change notification settings - Fork1
Rust JSON Schema validator and JSON coercer
License
broidHQ/valico
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Valico is a validation and coercion tool for JSON objects, written in Rust. 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.
Valico has two features:
- DSL — a set of simple validators and coercers inspired byGrape. It has built-in support for common coercers, validators and can return detailed error messages if something goes wrong.
- JSON Schema — An implementation of JSON Schema, based on IETF's draft v4.
References:
- http://json-schema.org
- http://json-schema.org/latest/json-schema-core.html
- http://json-schema.org/latest/json-schema-validation.html
# Cargo.tomlvalico ="1"
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.
- jsonway — JSON building DSL and configurable serializers for Rust
It passes the entireJSON-Schema-Test-Suite except for remoteRefs and maxLength/minLength when using unicode surrogate pairs. It also can validate your schema and give you an explanation about what is wrong in it.
use serialize::json;use valico::json_schema;use std::old_io::fs;fnmain(){let json_v4_schema: json::Json = fs::File::open(&Path::new("tests/schema/schema.json")).ok().unwrap().read_to_string().ok().unwrap().parse().unwrap();letmut scope = json_schema::Scope::new();let schema = scope.compile_and_return(json_v4_schema.clone()).ok().unwrap();println!("Is valid: {}", schema.validate(&json_v4_schema).is_valid())}
Valico goes withvalico::json_schema::schema(|scheme| { /* .. */ }) -> json::Json function that allows to use simple DSL to generate your schemes. It allows you not to use strings and raw JSON manipulation. It also prevent some kinds of spelling and type errors.
builder::schema(|s|{ s.properties(|properties|{ properties.insert("prop1", |prop1|{ prop1.maximum(10f64,false);});}); s.pattern_properties(|properties|{ properties.insert("prop.*", |prop|{ prop.maximum(1000f64,false);});}); s.additional_properties_schema(|additional|{ additional.maximum(5f64,false)});})
TODO more docs about JSON Schema here
All Valico stuff is making by Builder instance. Below is a simple example showing how one can create and setup Builder:
let params =Builder::build(|params|{params.req_nested("user",Builder::list(), |params|{params.req_typed("name", json_dsl::string());params.req_typed("friend_ids", json_dsl::array_of(json_dsl::u64()))});});
Laterparams instance can be used to process one or more JSON objects with it'sprocess method with signaturefn process(&self, tree: &mut JsonObject) -> ValicoResult<()>.
Note that Valico willmutate borrowed JSON value if some coercion is needed.
Example:
externcrate valico;externcrate serialize;use serialize::json;use serialize::json::{ToJson};use valico::{Builder,MutableJson};fnmain(){let params =Builder::build(|params|{ params.req_nested("user",Builder::list(), |params|{ params.req_typed("name", json_dsl::string()); params.req_typed("friend_ids", json_dsl::array_of(json_dsl::u64()))});});letmut 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 thespecs for more details and examples.
You can define validations and coercion options for your parameters using aBuilder::build block. Parameters can beoptional andrequired. 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:
// Parameter is required, no coercionfnreq_defined(&mutself,name:&str);// Parameter is required, with coercionfnreq_typed(&mutself,name:&str,coercer:Box<Coercer>);// Parameter is required, with coercion and nested checksfnreq_nested(&mutself,name:&str,coercer:Box<Coercer>, nest_def: |&mutBuilder|);// Parameter is required, setup with Param DSLfnreq(&mutself,name:&str, param_builder: |&mutParam|);// Parameter is optional, no coercionfnopt_defined(&mutself,name:&str);// Parameter is optional, with coercionfnopt_typed(&mutself,name:&str,coercer:Box<Coercer>);// Parameter is optional, with coercion and nested checksfnopt_nested(&mutself,name:&str,coercer:Box<Coercer>, nest_def: |&mutBuilder|);// Parameter is required, setup with Param DSLfnopt(&mutself,name:&str, param_builder: |&mutParam|);
Available list of coercers:
- json_dsl::i64()
- json_dsl::u64()
- json_dsl::f64()
- json_dsl::string()
- json_dsl::boolean()
- json_dsl::null()
- json_dsl::array()
- json_dsl::array_of()
- json_dsl::encoded_array() — use it for string-encoded arrays e.g. "red,green,blue" -> ["red", "green", "blue"]
- json_dsl::encoded_array_of() — use it for string-encoded arrays of some type e.g. "1,2,3" -> [1, 2, 3]
- json_dsl::object()
Example of usage:
let params =Builder::build(|params|{ params.req_typed("id", json_dsl::u64()); params.req_typed("name", json_dsl::string()); params.opt_typed("is_active", json_dsl::boolean()); params.opt_typed("tags", json_dsl::array_of(json_dsl::strings()));});
You can specify rules to nesting processing forlists andobjects:
let params =Builder::build(|params|{ params.req_nested("user", json_dsl::object(), |params|{ params.req_typed("name", json_dsl::string()); params.opt_typed("is_active", json_dsl::boolean()); params.opt_typed("tags", json_dsl::array_of(json_dsl::strings()));});});let params =Builder::build(|params|{ params.req_nested("users",Builder::list(), |params|{ params.req_typed("name", json_dsl::string()); params.opt_typed("is_active", json_dsl::boolean()); params.opt_typed("tags", json_dsl::array_of(json_dsl::strings()));});});
Nesting level is not limited in Valico.
DSL allows to use JSON Schema validations to validate objects at the Builder level and the Param level:
let params = json_dsl::Builder::build(|params|{ params.req("a", |a|{ a.schema(|schema|{ schema.integer(); schema.maximum(10f64,false);})});});
Note that JSON Schema validates object AFTER coerce pass:
letmut params = json_dsl::Builder::build(|params|{ params.req("a", |a|{ a.coerce(json_dsl::u64()); a.schema(|schema|{ schema.maximum(10f64,false);})});});
Don't forget to create ajson_schema::Scope BEFORE processing:
letmut scope = json_schema::Scope::new();params.build_schemes(&mut scope).unwrap();
You can use DSL block to setup parameters with more flexible way:
let params =Builder::build(|params|{ params.req("user", |user|{ user.desc("Parameter is used to create new user"); user.coerce(json_dsl::object());// this allows null to be a valid value user.allow_null(); user.nest(|params|{ params.req_typed("name", json_dsl::string()); params.opt("kind", |kind|{ kind.coerce(json_dsl::string());// optional parameters can have default values kind.default("simeple_user".to_string())});});});});
DSL supports several parameter validations. They considered outdated and likely to beremoved in the future in favour of JSON Schema validation.
Parameters can be restricted to a specific set of values withallow_values:
let params =Builder::build(|params|{ params.req("kind", |kind|{ kind.coerce(json_dsl::string()); kind.allow_values(["circle".to_string(),"square".to_string()]);})})
Some values can be rejected withreject_values:
let params =Builder::build(|params|{ params.req("user_role", |kind|{ kind.coerce(json_dsl::string()); kind.reject_values(["admin".to_string(),"manager".to_string()]);})})
String values can be tested with Regex:
let params =Builder::build(|params|{ params.req("nickname", |a|{ a.coerce(json_dsl::string());// force all nicknames to start with "Amazing" a.regex(regex!("^Amazing"));})});
Sometimes it's usefull to use some custom function as validator:
let params =Builder::build(|params|{ params.req("pushkin_birthday", |a|{ a.coerce(json_dsl::u64());fnguess(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.
let params =Builder::build(|params|{ params.opt_defined("vodka"); params.opt_defined("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.
let params =Builder::build(|params|{ params.opt_defined("vodka"); params.opt_defined("beer"); params.mutually_exclusive(["vodka","beer"]);});
Multiple sets can be defined:
let params =Builder::build(|params|{ params.opt_defined("vodka"); params.opt_defined("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 'exactly_one_of', ensuring that exactly one parameter gets selected.
let params =Builder::build(|params|{ params.opt_defined("vodka"); params.opt_defined("beer"); params.exactly_one_of(["vodka","beer"]);});
Parameters can be defined as 'at_least_one_of', ensuring that at least one parameter gets selected.
let params =Builder::build(|params|{ params.opt_defined("vodka"); params.opt_defined("beer"); params.opt_defined("wine"); params.exactly_one_of(["vodka","beer","wine"]);});
Sometimes it's usefull to use some custom function as validator:
let params =Builder::build(|params|{ params.req_defined("monster_name");fnvalidate_params(_:&JsonObject) ->Result<(),String>{Err("YOU SHALL NOT PASS".to_string())} params.validate_with(validate_params);});
One can use custom validator. Docs in Progress.
About
Rust JSON Schema validator and JSON coercer
Resources
License
Stars
Watchers
Forks
Packages0
Languages
- Rust99.7%
- Other0.3%