GraphQL Schema Language Cheat Sheet
Guaranteed to make you a better and respected GraphQLinguist amongst your peers.
What is GraphQL Schema Language?
It is a shorthand notation to succinctly express the basic shape of your GraphQL schema and its type system.
Example of a typical GraphQL schema expressed in shorthand.
interface Entity {
id: ID!
name: String
}type User implements Entity {
id: ID!
name: String
age: Int
balance: Float
is_active: Boolean
friends: [User]!
}type Root {
me: User
users(limit: Int = 10): [User]!
friends(forUser: ID!, limit: Int = 5): [User]!
}schema {
query: Root
mutation: ...
subscription: ...
}
(Ain’t it purrtyyy?)
Basics
Schema
=======GraphQL Schema => schemaBuilt-in scalar types
=====================GraphQL Int => Int
GraphQL Float => Float
GraphQL String => String
GraphQL Boolean => Boolean
GraphQL ID => IDType Definitions
================Scalar Type => scalar
Object Type => type
Interface Type => interface
Union Type => union
Enum Type => enum
Input Object Type => inputType Markers
============Non-null Type => <type>! e.g String!
List Type => [<type>] e.g [String]
List of Non-null Types => [<type>!] e.g [String!]
Non-null List Type => [<type>]! e.g [String]!
Non-null List of Non-null Types => [<type>!]! e.g [String!]!
Examples
Below are further examples to illustrate how we can use the above Shorthand Notation to describe our schema.
Input Arguments
Basic Input
============type Root {
users(limit: Int): [User]!
}
Input with default value
=========================type Root {
users(limit: Int = 10): [User]!
}
Input with multiple args
=========================type Root {
users(limit: Int, sort: String): [User]!
}Input with multiple args and default values
===========================================type Root {
users(limit: Int = 10, sort: String): [User]!
}ortype Root {
users(limit: Int, sort: String = "asc" ): [User]!
}ortype Root {
users(limit: Int = 10, sort: String = "asc" ): [User]!
}
Interfaces
- Object implementing an Interface
interface Foo {
is_foo: Boolean
}type Bar implements Foo {
is_foo: Boolean
is_bar: Boolean
}
- Object implementing multiple Interfaces
interface Foo {
is_foo: Boolean
}interface Goo {
is_goo: Boolean
}type Bar implements Foo, Goo {
is_bar: Boolean
is_foo: Boolean
is_goo: Boolean
}
Unions
- Union of a single Object
type Foo {
name: String
}union SingleUnion = Footype Root {
single: SingleUnion
}
- Union of multiple Objects
type Foo {
name: String
}type Bar {
is_bar: String
}union MultipleUnion = Foo | Bartype Root {
multiple: MultipleUnion
}
Enums
enum RGB {
RED
GREEN
BLUE
}type Root {
color: RGB
}
Input Object Types
input ListUsersInput {
limit: Int
since_id: ID
}type Root {
users(params: ListUsersInput): [Users]!
}
Custom Scalar
scalar Urltype User {
name: String
homepage: Url
}
There you go, all you need to know about GraphQL’s shorthand notation. (Probably? Let me know if I had missed anything out)
Now go forth, and wield the power that you have just been bestowed upon with, responsibly.
Extras
- Head over to the GitHub repo (https://github.com/sogko/graphql-shorthand-notation-cheat-sheet) for download links (PDF and PNG available)
- utilities/schemaPrinter.js
graphql-js comes with an utility to transform your schema into a shorthand notation representation. - Check out the official documentation on GraphQL Type System.