Schema Design
Workshop
Eve Porcello
@eveporcello
Agenda
- Intro to the Schema Definition Language
- Creating Schema Types
- Nullable vs. Non-nullable Fields
- Design Considerations
Tahoe City, CA
GraphQL is a spec that describes:
A Query Language
A Schema Definition Language
GraphQL Scalar Types
Int
Float
String
Boolean
ID
id: ID!
name: String!
GraphQL Scalar Types
type Photo {
id: ID!
name: String!
url: String!
description: String
rating: Float
private: Boolean!
}
GraphQL Object Types
name: String!
Nullable vs. Non-nullable
description: String
type Query {
totalUsers: Int!
}
Root Queries
type Query {
totalUsers(role: ROLE!): Int!
}
Arguments
type User {
postedPhotos: [Photo!]!
}
Lists
photos: [Photo]
Nullable vs. Non-nullable Lists
photos: [Photo]!
photos: [Photo!]!
Nullable list of nullable values
Non-nullable list of nullable values
Non-nullable list of non-nullable values
Enums
enum PhotoCategory {
PORTRAIT
ACTION
LANDSCAPE
}
Root Mutation
type Mutation {
postPhoto: Boolean!
}
Arguments
type Mutation {
postPhoto (name: String!): Photo!
}
Input Types
input PostPhotoInput {
name: String!
category: PhotoCategory=PORTRAIT
description: String
}
Input Types
mutation addPhoto ($input: PostPhotoInput!) {
postPhoto(input: $input) {
id
name
url
}
}
{
"input": {
"name": "Desert Sunset",
"description": "Sunset over Sedona",
"category": "LANDSCAPE"
}
}
Query Variables
Root Subscription
type Subscription {
newPhoto: Photo!
}
Custom Scalars
scalar DateTime
type Photo {
created: DateTime!
updated: DateTime!
}
One-to-One Connection
type Photo {
postedBy: User!
}
One-to-Many Connection
type User {
postedPhotos: [Photo!]!
}
Many-to-Many Connection
type Student {
schedule: [Course!]!
}
type Course {
students: [Student!]!
}
City to City
type City {
name: String!
connections: [City!]!
}
BOISE
SUN VALLEY
BEND
155 MILES
318 MILES
Through Types
type City {
name: String!
connections: [Connection!]!
}
type Connection {
distance: Int!
to: City!
}
BOISE
SUN VALLEY
155 MILES
BEND
318 MILES
Through Types w/ Pagination
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: ID!
endCursor: ID!
}type CityEdge {
node: City!
cursor: ID!
}type City {
name: String!
connections(
first: Int!,
after: ID!
): [CityConnection!]!
}
type CityConnection {
edges: [CityEdge]
pageInfo: PageInfo!
}
Building the
Pet Library Schema
Agenda
- Interfaces & Union Types
- Filtering & Pagination
- Scaling a Schema
Keep In Mind:
-
What Clients Need
-
Specific, Consistent Naming
-
Custom Objects Over Scalar Values
Union Types
type Schedule {
agenda: [AgendaItem!]!
}
union AgendaItem = StudyGroup | Workout
query {
agenda {
...on Workout {
name
reps
}
...on StudyGroup {
name
subject
students
}
}
}
Query
Interfaces
interface ScheduleItem {
name: String!
start: Int
end: Int
}
type StudyGroup implements ScheduleItem {
name: String!
start: Int
end: Int
students: Int!
}
type Workout implements ScheduleItem {
name: Location!
start: Int
end: Int
reps: Int!
}
type Query {
agenda: [ScheduleItem!]!
}
enum PetCategory
DOG
CAT
STINGRAY
RABBIT
type Pet
id: ID!
name: String!
category: PetCategory!
...
HORSE
sleepAmount: Int
curious: Boolean
favoriteFood: String
floppy: Int
good: Boolean
chill: Boolean
fast: Boolean
streetsmart: Boolean
majestic: Boolean
interface Pet
type Cat implements Pet
id: ID!
name: String
...
sleepAmount: Int
curious: Boolean
id: ID!
name: String!
weight: Float
status: PetStatus
photo: Photo
dueDate: Date
inCareOf: Customer
type Dog implements Pet
id: ID!
name: String
...
good: Boolean
type Rabbit implements Pet
id: ID!
name: String
...
favoriteFood: String
floppy: Int
type Stingray
implements Pet
id: ID!
name: String
...
chill: Boolean
fast: Boolean
type Horse
implements Pet
id: ID!
name: String
...
streetsmart: Boolean
majestic: Boolean
type *TBDFuturePet
implements Pet
id: ID!
name: String
...
newField: _____
newField: _____
Union Types
type Query {
familyPets: [FamilyPets!]!
}
union FamilyPet = Cat | Dog
Query
query {
familyPets {
__typename
...on Cat {
name
weight
}
...on Dog {
name
status
}
}
}