GraphQL Schema Language Cheat Sheet

Hafiz Ismail
wehavefaces
Published in
3 min readApr 16, 2016

Guaranteed to make you a better and respected GraphQLinguist amongst your peers.

Links to the PDF and high-res PNG versions available at the end of the article.

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 => ID
Type Definitions
================
Scalar Type => scalar
Object Type => type
Interface Type => interface
Union Type => union
Enum Type => enum
Input Object Type => input
Type 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

  1. Head over to the GitHub repo (https://github.com/sogko/graphql-shorthand-notation-cheat-sheet) for download links (PDF and PNG available)
  2. utilities/schemaPrinter.js
    graphql-js comes with an utility to transform your schema into a shorthand notation representation.
  3. Check out the official documentation on GraphQL Type System.

Follow me @sogko on Twitter and Github, because that’s a thing now.

Published in wehavefaces

software engineer | open-source buccaneer | aphrostysicist

Written by Hafiz Ismail

aphrostysicist (æf.rəʊ ˈstɪz.ɪ.sɪst) : noun - someone who is not an astrophysicist | @sogko

Responses (6)

What are your thoughts?

This is a really nice writeup! I’m working on an open-source toolkit called graphql-tools that can help transform the shorthand notation into an executable schema with a bit of additional information, and I’m also writing a guide / documentation for it. Would love to get your feedback on it!

Would you mind telling me which tool you used to create the cheatsheet?

Thanks for the Cheat Sheet! I’m not currently interested in GraphQL but I find it very nice. Could you please share how did you create it?