Struct Shape

pub struct Shape { /* private fields */ }

The shape::Shape struct provides a recursive, immutable, reference-counted tree/DAG format for representing and enforcing common structures and usage patterns of JSON-like data.

The Shape system is not bound to any particular programming language, so it does not inherit a data model that it must represent and defend, yet it must adopt/assume some concrete data model, since a type system without a data model to enforce is as useful as a straitjacket on a coat rack. JSON was chosen for its relative simplicity, its ubiquity as a data interchange format used across programming languages, and because JSON is often used in scenarios without a static type system to help catch errors before runtime.

The Shape system has no source syntax for denoting shapes directly, but you can use the Shape::* helper functions to create shapes programmatically, in Rust. Shape::pretty_print() provides a human-readable representation of a Shape for debugging and testing purposes.

All in all, this Static Shape System (SSS) supports the following type-theoretic features:

• Primitive shapes: Bool, String, Int, Float, Null
• Singleton primitive shapes: true, false, "hello", 42, null
• Array shapes, supporting both static tuples and dynamic lists
• Object shapes, supporting both static fields and dynamic string keys
• One<S1, S2, ...> union shapes, representing a set of shape alternatives
• All<S1, S2, ...> intersection shapes, representing a set simultaneous requirements
• shape.field(name) and shape.item(index) methods for accessing the shape of a subproperty of a shape
• Name shape references, with support for symbolic subproperty shape access
• Error shapes, representing a failure of shape processing, with support for chains of errors and partial shape data
• None shapes, representing the absence of a value (helpful for representing optionality of shapes)
• subshape.satisfies(supershape) and supershape.accepts(subshape) methods for testing shape relationships
• shape.accepts_json(json) method for testing whether concrete JSON data satisfies some expected shape
• shape.pretty_print() method for debugging and testing

Implementations

impl Shape

pub fn accepts(&self, other: &Shape) -> bool

Returns true if the other shape meets all the expectations of the self shape. In set theory terms, the set of all values accepted by other is a subset of the set of all values accepted by self.

pub fn accepts_json(&self, json: &Value) -> bool

Returns true iff the given serde_json JSON data satisfies self.

pub fn accepts_json_bytes(&self, json: &Value) -> bool

Returns true iff the given serde_json_bytes JSON data satisfies self.

pub fn validate(&self, to_be_validated: &Shape) -> Vec<ShapeMismatch>

Validates that all expectations of the self shape are met by the to_be_validated shape, erroring with a non-empty vector of ShapeMismatch errors when validation fails.

Note that validate is closer to accepts than satisfies in terms of the direction of the comparison, which is why the implementation uses to_be_validated.satisfies_at_path(self, ...) rather than self.satisfies_at_path(to_be_validated, ...).

pub fn validate_json(&self, json: &Value) -> Vec<ShapeMismatch>

Shape::validate_json is to Shape::validate as Shape::accepts_json is to Shape::accepts.

pub fn validate_json_bytes(&self, json: &Value) -> Vec<ShapeMismatch>

Shape::validate_json_bytes is to Shape::validate as Shape::accepts_json_bytes is to Shape::accepts.

pub fn satisfies(&self, other: &Shape) -> bool

Returns true if the self shape meets all the expectations of the other shape. In set theory terms, self satisfying other means the set of all values accepted by self is a subset of the set of all values accepted by other.

The satisfies method is the inverse of the accepts method, in the sense that a.accepts(b) is equivalent to b.satisfies(a). For historical reasons, the bulk of the accepts/satisfies logic happens in the internal satisfies_at_path method, though I have since realized the accepts direction generalizes a bit better to situations where other is not a Shape, such as Shape::accepts_json(&self, json: &serde_json::Value).

impl Shape

pub fn field(&self, field_name: &str) -> Shape

Returns a new Shape representing the shape of a given subproperty (field name) of the self shape.

pub fn any_field(&self) -> Shape

Returns a new Shape representing the union of all field shapes of object shapes, or just the shape itself for non-object shapes.

pub fn item(&self, index: usize) -> Shape

Returns a new Shape representing the shape of a given element of an array shape.

pub fn any_item(&self) -> Shape

Returns a new Shape representing the union of all element shapes of array shapes, or just the shape itself for non-array shapes.

impl Shape

pub fn pretty_print(&self) -> String

Returns a string representation of the Shape.

Please note: this display format does not imply an input syntax or parser for the shape language. To create new Shape elements, use the various Shape::* helper functions.

impl Shape

pub fn from_json(json: &JSON) -> Self

Derive a Shape from a JSON value, which is almost a lossless conversion except that floating point literals get the general ShapeCase::Float shape, ignoring their particular values.

pub fn from_json_bytes(json: &JSONBytes) -> Self

Derive a Shape from a JSON value using the serde_json_bytes crate.

impl Shape

pub fn case(&self) -> &ShapeCase

When boolean helper methods like .is_none() and .is_null() are not enough, you can match against the underlying ShapeCase by obtaining an immutable &ShapeCase reference using the shape.case() method.

pub fn bool() -> Self

Returns a Shape that accepts any boolean value, true or false.

pub fn bool_value(value: bool) -> Self

Returns a Shape that accepts only the specified boolean value.

pub fn string() -> Self

Returns a Shape that accepts any string value.

pub fn string_value(value: &str) -> Self

Returns a Shape that accepts only the specified string value.

pub fn int() -> Self

Returns a Shape that accepts any integer value.

pub fn int_value(value: i64) -> Self

Returns a Shape that accepts only the specified integer value.

pub fn float() -> Self

Returns a Shape that accepts any floating point value.

pub fn null() -> Self

Returns a Shape that accepts only the JSON null value.

pub fn is_null(&self) -> bool

pub fn name(name: &str) -> Self

Returns a symbolic reference to a named shape, potentially not yet defined.

In order to add items to the subpath of this named shape, call the .field(name) and/or .item(index) methods.

Note that variable shapes are represented by ShapeCase::Name where the name string includes the initial $ character.

pub fn empty_map() -> IndexMap<String, Self>

Useful for obtaining the kind of IndexMap this library uses for the ShapeCase::Object variant.

pub fn empty_object() -> Self

Returns a Shape that accepts any object shape, regardless of the other shape’s fields or rest shape, because an empty object shape {} imposes no expectations on other objects (except that they are objects).

In the other direction, an empty object shape {} can satisfy itself or any Dict<V> shape (where the Dict may be dynamically empty), but cannot satisfy any object shape with non-empty fields.

pub fn object(fields: IndexMap<String, Shape>, rest: Shape) -> Self

To get a compatible empty mutable [IndexMap] without directly depending on the indexmap crate yourself, use Shape::empty_map().

pub fn record(fields: IndexMap<String, Shape>) -> Self

Returns a Shape that accepts any object shape with the given static fields, with no dynamic fields considered.

pub fn dict(value_shape: Shape) -> Self

Returns a Shape that accepts any dictionary-like object with dynamic string properties having a given value shape.

pub fn array(prefix: &[Shape], tail: Shape) -> Self

Arrays, tuples, and lists are all manifestations of the same underlying ShapeCase::Array representation.

pub fn tuple(shapes: &[Shape]) -> Self

A tuple is a ShapeCase::Array with statically known (though possibly empty) element shapes and no dynamic tail shape.

pub fn list(of: Shape) -> Self

A List<S> is a ShapeCase::Array with an empty static prefix and a dynamic element shape S.

pub fn empty_array() -> Self

Returns a Shape that accepts any empty array, returning Shape::none() for all index accesses.

pub fn one(shapes: &[Shape]) -> Self

Returns a ShapeCase::One union of the given shapes, simplified.

pub fn all(shapes: &[Shape]) -> Self

Returns a ShapeCase::All intersection of the given shapes, simplified.

pub fn none() -> Self

pub fn is_none(&self) -> bool

pub fn error(message: &str) -> Self

Report a failure of shape processing.

pub fn is_error(&self) -> bool

pub fn error_with_range(message: &str, range: OffsetRange) -> Self

Report a failure of shape processing associated with a specific source OffsetRange.

pub fn error_with_partial(message: &str, partial: Shape) -> Self

Report a failure of shape processing associated with a partial/best-guess shape that may still be useful.

pub fn error_with_range_and_partial( message: &str, range: OffsetRange, partial: Shape, ) -> Self

Trait Implementations

impl Clone for Shape

fn clone(&self) -> Shape

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Shape

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Shape

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Hash for Shape

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for Shape

fn eq(&self, other: &Shape) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Shape

impl Send for Shape

impl StructuralPartialEq for Shape

impl Sync for Shape

Since we’re using std::sync::Arc for reference counting, and Shape is an immutable structure, we can safely implement Send and Sync for Shape.