Rust API reference#

The Rust crate is shape-schema (the library is shape: use shape::…), in rs/. It matches the canonical TypeScript for validation outcomes, produced values and exact error text; the parity page lists its divergences. This page is the Rust surface and its idioms; the behaviour of each builder is in the builder reference.

Compilation#

use shape::{shape, Options, Schema, Spec, Token};

let s: Schema = shape(spec); // any `impl Into<Spec>`
let s = Schema::new(spec); // the same
let s = Schema::with_options(spec, &Options::default());
let s = Schema::parse("String.Min(2)")?; // the string form; Err(ExprError)

A Spec is what a schema is compiled from:

shape! writes a spec as the example it is, in the serde_json::json! style: objects in braces, arrays in brackets, the type tokens bare, and any other Rust expression a spec can be made from:

use shape::{min, shape, Schema, Token};

let s = Schema::new(shape!({
    "name": String,
    "port": 8080,
    "tags": [String],
    "age": min(0, Token::Integer),
    "addr": { "zip": String },
}));

Schema methods#

validate takes its input by value and produces in place. Value::Undefined is no value at all, as a bare shape() call is in TypeScript. The Node of the tree is a plain struct (kind: Kind, required, its children, its befores and afters as Validators); Node::of(kind) is a bare one.

Values#

shape::Value is what is validated and produced: what JSON can carry, plus the four things the canonical behaviour needs and JSON cannot say.

From conversions exist for the Rust scalars, &str, String, Vec, Map and BigInt, and, with the serde feature, both ways with serde_json::Value (an undefined property is dropped, NaN and a function become null, a date its ISO text). The accessors are is_undefined(), is_null(), as_f64(), as_str(), as_arr(), as_obj() and type_of(), the JavaScript typeof.

Tokens#

Token::{Any, String, Number, Boolean, Object, Array, Function, Integer, Date, BigInt}. A token is required (but for Any) and carries the kind's empty value as the default it injects once made optional. Token::Object accepts any keys; Token::Array any elements.

Builders#

Every builder is a free function taking the spec it applies to as its last argument, and a chain method on Node. buildize(spec) is the node a spec compiles to, where a chain starts; pass any() for the bare form.

The chain method for Default is default_to, to leave Default::default alone; the one for Type is type_, since type is a keyword. Builders consume the node they are given and return it, so a compiled Schema is immutable and Send + Sync; a base to reshape twice is cloned first.

The argument types: pick and omit take a Names, made from a &str, a String, a Vec or an array of them; type_ takes a TypeRef, made from a Kind, a Token, a kind's name or a Node; check_re takes a regex::Regex; exact any iterator of values. ReferOptions has fill (substitute even when the value is absent) and strict (a name with no define is an error); RenameOptions has keep (keep the original key too) and claim (other keys to read from when the renamed one is missing).

A builder called with a wrong argument (min("x", ..), len(-1, ..), define("", ..), pick("z", ..)) cannot fail as TypeScript's throwing builders do; it returns a fault node that accepts nothing and reports the message at validation. The string form refuses it instead: expr and Schema::parse return an ExprError for a wrong argument (Shape: Min needs a number) as for a malformed expression, which is what expr throws in TypeScript.

Custom validators#

check, before and after take Fn(&mut State, &mut Update) -> bool, Send + Sync + 'static (the ValidatorFn type). The State is the value, the node, the path (path_arr, a slice of PathPart; path_str() dotted; path_keys() as strings), the key, parent_is_array, absent (missing, rather than present and null), is_match (a valid call: nothing is produced), check_name, and the Context; the Update is what the validator reports: err (an UpdateErr: a text with $PATH and $VALUE, a FieldError, or several), why and mark, a replacement val, a replacement node, done to stop the node's other checks, and fatal to end the walk's errors there. transform takes Fn(Value, &mut State) -> Value (the TransformFn type).

The Context carries custom, a typed map of the caller's own state (get::<T>, set), refs, the defined shapes met on the call, and err, every error raised.

Options#

Options has three switches, as the canonical ShapeOptions does: key_expr (on: "a: Min(1)" keys are key expressions), meta with meta_suffix (off: "a$$" keys are metadata for "a") and val_expr with val_expr_mark (off: the string under the mark key is an expression applied to the object).

Errors#

ValidationError holds issues: Vec<FieldError> and prints them joined by newlines, the canonical text. A FieldError has path, path_arr, key, kind, value, why, mark, text, args and check, and prints its text; see the error reference. The why codes and mark numbers are the WHY_* and MARK_* constants of shape::error. Both types are std::error::Error, as are IntoError (Validation or Deserialize, from validate_into), ExprError, ArguError and JsonSchemaError, the last three newtypes of their message.

The string form#

expr(src) parses an expression to a Node; expr_apply(src, carrier) applies one to a spec, as key and value expressions do; stringify_node(&node, inline) renders a node as its spec text, inline writing a string value bare, as a composite message does. The grammar is the one of the string DSL.

JSON Schema#

Schema::json_schema() and shape::json_schema(&node) export; shape::from_json_schema(&Value) imports, returning a Spec to compile or compose further, or a JsonSchemaError. shape::jsonschema::JSON_SCHEMA_DRAFT is the $schema URL written.

Positional arguments (Argu)#

use shape::{skip, Spec, Token, Value};

let argu = shape::Argu::new("mylib");
let sig = argu.signature(
    "foo",
    [
        ("a", Spec::from(Token::Number)),
        ("b", Spec::from(skip(Token::String))),
    ],
)?;
let named: shape::Map = sig.apply(vec![Value::from(2)])?; // {"a": 2, "b": Undefined}

argu.validate(args, whence, spec) compiles and applies in one call. A skip slot is optional and shifts the ones after it; a rest slot captures whatever remains; too many arguments, or one that does not match, is an ArguError with the canonical text (mylib (foo): Too many arguments for type signature (was 3, expected 2)).

Version#

shape::VERSION is the crate version.