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.

When called with empty locations, returns a clone of a cached canonical singleton — two atomic refcount bumps instead of two heap allocations.

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.

When called with empty locations, returns a clone of a cached canonical singleton.

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.

When called with empty locations, returns a clone of a cached canonical singleton.

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.

When called with empty locations, returns a clone of a cached canonical singleton.

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

Returns a Shape that accepts only the JSON null value.

When called with empty locations, returns a clone of a cached canonical singleton.

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 closed {} shape (no fields, no rest — only the literal empty object is accepted), use Shape::empty_object.

When called with empty locations, returns a clone of a cached canonical singleton.

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

Returns a closed empty object Shape: no declared fields and no dynamic properties, so only the literal empty object {} satisfies it. This is the counterpart to Shape::any_object (the open form that accepts any object). There is no open_empty_object / closed_* pair here because the two forms are distinct enough to name directly: any_object (open) and empty_object (closed {}).

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 open_record( fields: IndexMap<String, Shape>, locations: impl IntoIterator<Item = Location>, ) -> Self

An open record is a ShapeCase::Object with statically known fields and an open (Unknown) rest, so it accepts objects that carry the declared fields plus any number of additional dynamic properties. For the closed counterpart that rejects keys not listed in fields, use Shape::closed_record.

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

👎Deprecated since 0.8.0:

use Shape::closed_record for a closed record, Shape::open_record if extra properties should be permitted, or Shape::any_object / Shape::is_object for the bare “any object?” probe

Previous name for a record constructor. The bare name record is ambiguous about whether extra dynamic properties are permitted, so it is deprecated in favor of the explicit pair. Its body produces the closed form (no rest, rejecting unlisted keys), matching the 0.7.0 behavior, so existing callers keep their semantics until they migrate. Pick explicitly: Shape::closed_record for that same closed record, or Shape::open_record to permit additional dynamic properties. The “any object?” probe is better served by Shape::any_object or Shape::is_object.

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

Returns a 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::open_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.8.0:

use Shape::closed_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 a tuple constructor. The bare name tuple is ambiguous about whether extra trailing elements are permitted, so it is deprecated in favor of the explicit pair. Its body produces the closed form (no tail, an exact n-tuple), matching the 0.7.0 behavior, so existing callers keep their semantics until they migrate. Pick explicitly: Shape::closed_tuple for that same exact n-tuple, or Shape::open_tuple to assert a prefix while allowing additional trailing elements. The “any array?” probe is better served by Shape::any_array or Shape::is_array.

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::closed_tuple.

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

A closed 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.

When called with empty locations, returns a clone of a cached canonical singleton.

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.

If what you want is to combine several partial descriptions of one value (a spread, a selection set accumulated field by field) rather than to constrain a value by several requirements at once, use Shape::merge, which is that operation under its own name. See its documentation for the three ways this simplification currently departs from set intersection, and why the distinction is worth recording at the call site.

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

Returns the shape of a value assembled by combining several partial descriptions of that same value: the composition, or “spread”, operator. Use it for { a: 1, ...$(expr) }-style spreads, for accumulating the output shape of a selection set one selection at a time, and generally wherever the inputs describe contributions to one value rather than constraints on it.

merge is the same operation as Shape::all today, and delegates to the same code path, so moving a call site from all to merge cannot change its result. The two names exist because that one operation is doing two jobs, and the jobs are coming apart.

Shape::all is documented as intersection, and on many inputs it is one, but the simplification departs from set intersection in three ways. Each is right for composition and wrong for intersection:

• Null absorbs. All<Bool(true), Null> simplifies to Null, which is what makes GraphQL-style null bubbling work. As an intersection it should be empty, since no value is both true and null.
• None drops. All<Int, None> simplifies to Int, so an optional contribution that turns out to be absent contributes nothing. As an intersection it should be empty, since None denotes absence and Int denotes values.
• Objects merge, and lose closedness. All<{a: Int}, {b: String}> declares both keys, which neither input accepts, and All<{a: Int}, {a: Int, ...}> is the open record, which is wider than either input. Combining two partial records is supposed to widen. An intersection never can.

Each of those breaks the law that makes an operation a meet, namely that every member accepts the intersection (a.accepts(All<a, b>)). So if All<..> is ever corrected towards true intersection, every call site that meant composition would quietly change meaning. Calling merge records which one you meant, so that when the two operations are given separate implementations, composition call sites keep composition semantics and intersection call sites move.

What this does and does not guarantee yet

Being the same function is what makes adopting merge free, and it is also the limit of what merge currently promises. Until the two are given separate implementations, merge tracks Shape::all, so a change to Shape::all changes merge with it. That includes changes already planned: array members are combined positionwise today, and are scheduled to stop being combined and to remain side by side as an exact intersection instead. Composing arrays through merge is therefore version-unstable across that release, while composing objects, records and primitives is not.

Concretely: adopt merge now for the intent it records, rely on it for object and record composition, and do not depend on its array behavior until the two operations have diverged.

As with Shape::all, locations should refer to the construct that caused the shapes to be combined, such as the spread or the selection set, and not to the individual inputs. If there is nothing useful to point a reader at, pass an empty iterator.

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.

When called with empty locations, returns a clone of a cached canonical singleton. Constructors that internally build an open rest / tail (Shape::open_record, Shape::open_tuple, Shape::any_object, Shape::any_array) inherit this caching.

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. Returns a clone of the cached canonical singleton.

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) -> impl Iterator<Item = &Error> + '_

Recursively iterate over 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).

Internally, errors are gathered into a single buffer in pre-order and returned via Vec::into_iter; this is a single allocation per call regardless of tree depth, where a naive recursive Vec-of-Vec-collecting implementation would allocate one per visited shape.

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 Eq for Shape

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

Equality operator ==.

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

Inequality operator !=.

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.