Module schema

High-level representation of a GraphQL type system document a.k.a. schema.

Compared to an ast::Document which follows closely the structure of GraphQL syntax, a Schema is organized for semantics first:

• Wherever something is meant to have a unique name (for example fields of a given object type), a collection is stored as IndexMap<Name, _> instead of Vec<_> in order to facilitate lookup by name while preserving source ordering.

• Everything from type system extensions is stored together with corresponding “main” definitions, while still preserving extension origins with Component<_>. so that most consumers don’t need to care about extensions at all, (For example, some directives can be applied to an object type extensions to affect fields defined in the same extension but not other fields of the object type.) See Component.

In some cases like SchemaDefinition, this module and the ast module define different Rust types with the same names. In other cases like Directive there is no data structure difference needed, so this module reuses and publicly re-exports some Rust types from the ast module.

“Build” errors

As a result of how Schema is structured, not all AST documents (even if filtering out executable definitions) can be fully represented: creating a Schema can cause errors (on top of any potential syntax error) for cases like name collisions.

When such errors (or in Schema::parse, syntax errors) happen, a partial schema is returned together with a list of diagnostics.

Structural sharing and mutation

Many parts of a Schema are reference-counted with Node (like in AST) or Component. This allows sharing nodes between documents without cloning entire subtrees. To modify a node or component, the make_mut method provides copy-on-write semantics.

Validation

The Type System section of the GraphQL specification defines validation rules beyond syntax errors and errors detected while constructing a Schema. The validate method returns either:

• An immutable Valid<Schema> type wrapper, or
• The schema together with a list of diagnostics

If there is no mutation needed between parsing and validation, Schema::parse_and_validate does both in one step.

Serialization

Schema and other types types implement Display and ToString by serializing to GraphQL syntax with a default configuration. serialize methods return a builder that has chaining methods for setting serialization configuration, and also implements Display and ToString.

Re-exports

pub use crate::Name;

pub use crate::ast::Directive;

pub use crate::ast::DirectiveDefinition;

pub use crate::ast::DirectiveLocation;

pub use crate::ast::EnumValueDefinition;

pub use crate::ast::FieldDefinition;

pub use crate::ast::InputValueDefinition;

pub use crate::ast::NamedType;

pub use crate::ast::Type;

pub use crate::ast::Value;

Structs

Component

A component of a type or schema, for example a field of an object type.

ComponentName

A GraphQL Name that is component of a type or schema, for example the name of a union member type.

DirectiveList

The list of Directives of a GraphQL type or schema, each either from the “main” definition or from an extension.

EnumType

The definition of an enum type, with all information from type extensions folded in.

ExtensionId

Represents the identity of a schema extension or type extension.

Implementers

The names of all types that implement a given interface. Returned by Schema::implementers_map.

InputObjectType

The definition of an input object type, with all information from type extensions folded in.

InterfaceType

ObjectType

The definition of an object type, with all information from type extensions folded in.

ScalarType

The definition of a scalar type, with all information from type extensions folded in.

Schema

High-level representation of a GraphQL type system document a.k.a. schema.

SchemaBuilder

SchemaDefinition

The schema definition and its extensions, defining root operations

UnionType

The definition of an union type, with all information from type extensions folded in.

Enums

ComponentOrigin

The origin of a Component: either a “main” definition like schema or type ExampleObj, or an extension like extend schema or extend type ExampleObj.

ExtendedType

The definition of a named type, with all information from type extensions folded in.

FieldLookupError

Error type of Schema::type_field: could not find the requested field definition