Spring Boot GraphQL Schema Specification is the set of rules governing Query Request and Response. GraphQL defines all the API descriptions in schema files written in Schema Definition Language sometimes also called SDL Syntex or SDL Notation.
Unlike Swagger which is external and can have old documentation, GraphQL has inbuilt latest API schema documentation publication capabilities.
The Spring Boot GraphQL Schema Specification describes what the API will serve. SDL also provides detailed information about interfaces, unions, fragments, reserved names, comments, directives, available operands, etc.GraphQL schema Specification can be read from here
Spring Boot GraphQL Schema Specification Principles
GraphQL was designed with some major principles in mind, let's see them.
Evolve
Api requirements change over time, some fields are added some are removed, and accordingly, GraphQL Schema also evolves. Rest API marks contract evolution with versioning and the client has to keep track of which API Version needs to be called, whereas GraphQL supports @deprecated directive that marks the removal of an attribute from the contract. Learn more about @deprecated directive
Schema-first
The Restful API design comes either from the return type Object of the API, Database schema, Java Domain Classes, etc. GraphQL proposes that schema design should be separated from the code so that only the required data will be included in it. GraphQL Schema are Strongly Typed, it precisely define the type, fields, and data constraints of GraphQL API.
SpringBoot GraphQL supports the schema-first approach, the schema is represented by the GraphQLSchema Object. it can be created by SDL or programmatically as well. All schema files should have .graphqls or .gqls extensions and are loaded from the src/main/resources/graphql directory.
The GraphQL schema majorly supports eight types of elements which are classified as Named types and and Wrapping Types.
Named Types
Each Named Type supports unique elements.
| Named Type | Description |
|---|---|
Scaler Types that support five built-in primitive types String, Int, Float, Boolean, and ID. |
|
GraphQL provides Object Types to hold and wrap a Type Object |
|
GraphQL provides an Abstract Type Interface, which defines all the fields and is implemented by Concrete Types. |
|
A Union is a combination of multiple values, it describes the list of possible objects, and GraphQL provides a Union Type. |
|
GraphQL Enum is used to describe a list of possible values, it can be used for Mutation or input and Type or output as well. |
|
GraphQL Schema defines Input Objects with Input Type, and Spring Boot Controller marks them with @Argument annotation. |
Wrapping Types
Wrapping Type works as a wrapper for named types.
| Named Type | Description |
|---|---|
| List | GraphQL provides Wrapping Types or List Type to hold and wrap a Named Type. |
| NonNull | GraphQL provides a NonNull Type, which makes sure the Input Type will have values. |
Input Types
Input Data Type of the API request
Output Type
Result of the API response
