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::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_json(&self, json: &Value) -> Option<ShapeMismatch>

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

pub fn validate_json_bytes(&self, json: &Value) -> Option<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 validate 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).

pub fn validate(&self, other: &Shape) -> Option<ShapeMismatch>

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

impl Shape

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

pub fn is_never(&self) -> bool

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

Returns a new Shape representing the input shape with any possibility of null replaced by None, but otherwise unchanged. This models the behavior of a ? optional chainining operator, which additionally silences some errors related to missing fields at runtime. When a ShapeCase::Name shape reference has a ? step in its subpath, that ? step can be applied to the shape when/if the named shape is declared/resolved, so the effect of the ? is not lost.

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

Returns a new Shape representing the input shape with any possibility of None removed, but otherwise unchanged. This models the behavior of a hypothetical ! non-None assertion operator. When a ShapeCase::Name shape reference has a ! step in its subpath, that ! step can be applied to the shape when/if the named shape is later declared/resolved, so the effect of the ! is not lost.

pub fn apply_name(&self, name: &Name) -> Self

impl Shape

pub fn pretty_print(&self) -> String

Returns a string representation of the Shape, including any attached errors as (err "message") suffix.

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.

pub fn pretty_print_without_errors(&self) -> String

Returns a string representation of the Shape without any error annotations. This is the most concise representation.

pub fn pretty_print_with_names(&self) -> String

Returns a string representation of the Shape with Name metadata included as <shape> (aka <name1>, <name2>) and error metadata as (err "message"). Errors are shown first, then names.

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 has_base_name(&self, base_name: impl Into<String>) -> bool

Returns true if this Shape is known by the given base name, among potentially multiple names it may have.

pub fn with_base_name( self, name: impl Into<String>, locs: impl IntoIterator<Item = Location>, ) -> Self

Assigns a base name to this Shape, propagating derived child names to all nested child shapes. This method is called automatically when adding shapes to a Namespace (which always requires providing a base name). The locs for this operation should indicate where the name came from in source code, if that information is available.

impl Shape

pub fn visit_shape<V: ShapeVisitor>( &self, visitor: &mut V, ) -> Result<V::Output, V::Error>

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 locations(&self) -> impl Iterator<Item = &Location>

Returns an iterator over all Locations associated with this shape.

pub fn names(&self) -> impl Iterator<Item = &Name>

Returns an iterator over all Names associated with this shape.

pub fn nested_base_names(&self) -> impl Iterator<Item = &str>

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

Returns an open object Shape with no declared fields, which accepts any object value because the unknown rest shape permits any dynamic property. Useful as an “is this any object?” probe via Shape::accepts, or directly via Shape::is_object. For the strictly closed {} shape (no fields, no rest — only the literal empty object is accepted), use Shape::strict_empty_object.

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

👎Deprecated since 0.7.0:

use Shape::any_object for the open form, or Shape::strict_empty_object if extras should be rejected

Previous name for Shape::any_object. The empty_object label was misleading because the shape it produced has accepted any object value since Shape::record and friends became open by default — only Shape::strict_empty_object actually requires the empty literal {}. Callers that meant the open form should migrate to Shape::any_object; callers that genuinely needed the closed empty-only form should migrate to Shape::strict_empty_object.

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

Returns a strictly closed empty object Shape: no declared fields and no dynamic properties. Only the literal empty object {} satisfies it. For the common case where an empty object is used as a placeholder that should accept any object value, use Shape::any_object instead.

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 an open record Shape: an object with the given static fields plus an unknown rest shape, so any additional dynamic properties are permitted. For a strictly closed record whose only satisfying values carry exactly the declared fields, use Shape::strict_record.

pub fn strict_record( fields: IndexMap<String, Shape>, locations: impl IntoIterator<Item = Location>, ) -> Self

Returns a strictly closed record Shape: an object with the given static fields and no dynamic properties. Values with additional keys not listed in fields are rejected. For the open variant that permits additional properties, use Shape::record.

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

👎Deprecated since 0.7.0:

use Shape::strict_tuple for an exact n-tuple, Shape::open_tuple if extras should be permitted, or Shape::any_array / Shape::is_array for the bare “any array?” probe

Previous name for the open-tailed tuple constructor. The bare name tuple is ambiguous — classical tuples are fixed-arity (closed), but Shape::tuple has been open-tailed since Shape::strict_tuple was introduced. Callers should pick explicitly: Shape::strict_tuple for an exact n-tuple (no extras), or Shape::open_tuple when they want to assert a prefix while allowing additional trailing elements. The “any array?” probe is better served by Shape::any_array or Shape::is_array.

The body of this function still produces the open form, so existing callers’ behavior is unchanged until they migrate.

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

An open tuple is a ShapeCase::Array with statically known leading element shapes and an open (Unknown) tail, so it accepts arrays starting with the declared prefix and continuing with any number of trailing elements of any shape. For the closed counterpart that accepts only arrays of the exact declared length, use Shape::strict_tuple.

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

A strict tuple is a ShapeCase::Array with statically known (though possibly empty) element shapes and no dynamic tail shape, so it accepts only arrays of exactly the same length and element shapes. For the open-tailed counterpart that permits extra trailing elements beyond the declared prefix, use Shape::open_tuple.

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

Returns an open ShapeCase::Array with no required leading elements and an unknown tail, so it accepts any array value. Useful as an “is this any array?” probe via Shape::accepts, or directly via Shape::is_array.

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 is_array(&self) -> bool

Returns true iff this shape would be accepted by Shape::any_array, i.e. every value the shape can take is an array. Recurses through ShapeCase::One (every branch must be an array), ShapeCase::All (at least one intersection member must be an array), and bound ShapeCase::Name shapes (the resolved shape must be an array).

pub fn is_object(&self) -> bool

Returns true iff this shape would be accepted by Shape::any_object, i.e. every value the shape can take is an object. Recurses through ShapeCase::One, ShapeCase::All, and bound ShapeCase::Name shapes in the same way as Shape::is_array.

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. Creates an Unknown shape with the error attached as metadata.

pub fn is_error(&self) -> bool

👎Deprecated since 0.7.0:

use has_errors() for recursive check or has_own_errors() for own-only

Returns true if this shape has any errors attached directly (not nested).

pub fn has_own_errors(&self) -> bool

Returns true if this shape has errors attached to it (not nested children).

pub fn has_errors(&self) -> bool

Returns true if this shape or any nested child has errors.

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

Iterate over errors attached to this shape (not nested children).

pub fn errors(&self) -> Vec<&Error>

Recursively collect all errors from this shape and its nested children. This traverses Array elements, Object fields, One/All variants, but does NOT follow Name references (to avoid cycles and because named shapes are conceptually separate).

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. The error is attached to the partial shape as metadata.

pub fn with_error(self, error: Error) -> Self

Clone the shape with an additional error attached.

pub fn with_locations<'a>( self, locations: impl IntoIterator<Item = &'a 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 duplicate 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: &Self) -> 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 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.