Posted in Information Technology, Software Engineering

What is GraphQL Schema Language?

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 => schema
Built-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]!
}
or
type Root {
  users(limit: Int, sort: String = "asc" ): [User]!
}
or
type 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 = Foo
type Root {
  single: SingleUnion
}
  • Union of multiple Objects
type Foo {
  name: String
}
type Bar {
  is_bar: String
}
union MultipleUnion = Foo | Bar
type 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 Url
type 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.

cheat sheet:

https://wehavefaces.net/graphql-shorthand-notation-cheatsheet-17cd715861b6

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s