Struct Shape

pub struct Shape {
    pub locations: Vec<Location>,
    /* 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

Fields

locations: Vec<Location>

The combination of locations which, combined, produce this shape.

Many cases will only have a single location, but when shapes are simplified, their locations are all retained in the result.

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::Value satisfies self.

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

Returns true iff the given [serde_json_bytes::Value] 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, locations: impl IntoIterator<Item = Location>, ) -> Shape

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

pub fn any_field(&self, locations: impl IntoIterator<Item = Location>) -> 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, locations: impl IntoIterator<Item = Location>, ) -> Shape

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

pub fn any_item(&self, locations: impl IntoIterator<Item = Location>) -> Shape

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

pub fn child(&self, key: Located<NamedShapePathKey>) -> Shape

Get a child shape, and add the provided locations to it.

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.

Note that all locations will be empty, because serde_json doesn’t track locations.

Panics

If the JSON value can’t be converted into a [serde_json_bytes::Value]

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

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

Note that all locations will be empty, because [serde_json_bytes] doesn’t track locations.

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(locations: impl IntoIterator<Item = Location>) -> Self

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

pub fn bool_value( value: bool, locations: impl IntoIterator<Item = Location>, ) -> Self

Returns a Shape that accepts only the specified boolean value.

pub fn string(locations: impl IntoIterator<Item = Location>) -> Self

Returns a Shape that accepts any string value.

pub fn string_value( value: &str, locations: impl IntoIterator<Item = Location>, ) -> Self

Returns a Shape that accepts only the specified string value.

pub fn int(locations: impl IntoIterator<Item = Location>) -> Self

Returns a Shape that accepts any integer value.

pub fn int_value( value: i64, locations: impl IntoIterator<Item = Location>, ) -> Self

Returns a Shape that accepts only the specified integer value.

pub fn float(locations: impl IntoIterator<Item = Location>) -> Self

Returns a Shape that accepts any floating point value.

pub fn null(locations: impl IntoIterator<Item = Location>) -> Self

Returns a Shape that accepts only the JSON null value.

pub fn is_null(&self) -> bool

pub fn name( name: &str, locations: impl IntoIterator<Item = Location> + Clone, ) -> 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(locations: impl IntoIterator<Item = Location>) -> 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, locations: impl IntoIterator<Item = Location>, ) -> 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>, locations: impl IntoIterator<Item = Location>, ) -> 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, locations: impl IntoIterator<Item = Location>, ) -> Self

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

pub fn array( prefix: impl IntoIterator<Item = Shape>, tail: Shape, locations: impl IntoIterator<Item = Location>, ) -> Self

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

pub fn tuple( shapes: impl IntoIterator<Item = Shape>, locations: impl IntoIterator<Item = Location>, ) -> 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, locations: impl IntoIterator<Item = Location>) -> Self

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

pub fn one( shapes: impl IntoIterator<Item = Shape>, locations: impl IntoIterator<Item = Location>, ) -> Self

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

Note that locations in this case should not refer to each individual inner shape, but to the thing that caused all of these shapes to be combined, like maybe a ->match. If there is no obvious cause to point users to, then the location should be empty.

pub fn all( shapes: impl IntoIterator<Item = Shape>, locations: impl IntoIterator<Item = Location>, ) -> Self

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

Note that locations in this case should not refer to each individual inner shape, but to the thing that caused all of these shapes to be combined, like maybe a IntfA & IntfB. If there is no obvious cause to point users to, then the location should be empty.

pub fn unknown(locations: impl IntoIterator<Item = Location>) -> Self

Returns a shape that accepts any JSON value (including ShapeCase::None and ShapeCase::Unknown), and is not accepted by any shape other than itself.

pub fn is_unknown(&self) -> bool

pub fn none() -> Self

Returns a shape representing the absence of a JSON value, which is satisfied/accepted only by itself.

Because this represents the absence of a value, it shouldn’t have a location. Basically, nothing can produce none alone, and if it were a union, that union would have its own location.

pub fn is_none(&self) -> bool

pub fn error( message: impl Into<String>, locations: impl IntoIterator<Item = Location>, ) -> Self

Report a failure of shape processing.

pub fn is_error(&self) -> bool

pub fn errors(&self) -> impl Iterator<Item = &Error>

Iterate over all errors within this shape, recursively

pub fn error_with_partial( message: impl Into<String>, partial: Shape, locations: impl IntoIterator<Item = Location>, ) -> Self

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

pub fn with_locations( &self, locations: impl IntoIterator<Item = Location>, ) -> Self

Clone the shape, adding the provided locations to the existing locations.

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 From<&Component<FieldDefinition>> for Shape

fn from(field: &Component<FieldDefinition>) -> Self

Converts to this type from the input type.

impl From<&ExtendedType> for Shape

fn from(ext: &ExtendedType) -> Self

Converts to this type from the input type.

impl From<&Name> for Shape

fn from(name: &Name) -> Self

Converts to this type from the input type.

impl From<&Node<EnumType>> for Shape

fn from(enum_type: &Node<EnumType>) -> Self

Converts to this type from the input type.

impl From<&Node<InputObjectType>> for Shape

fn from(input_object_type: &Node<InputObjectType>) -> Self

Converts to this type from the input type.

impl From<&Node<InterfaceType>> for Shape

fn from(interface_type: &Node<InterfaceType>) -> Self

Converts to this type from the input type.

impl From<&Node<ObjectType>> for Shape

fn from(object_type: &Node<ObjectType>) -> Self

Converts to this type from the input type.

impl From<&Node<UnionType>> for Shape

fn from(union_type: &Node<UnionType>) -> Self

Converts to this type from the input type.

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.