GraphQL Schema Definition Language — Defining Types, Fields, and Relationships

In this tutorial, you will learn about Graphql Schema Definition Language. We cover key concepts, practical examples, and best practices to help you master this topic.

GraphQL Schema Definition Language (SDL) is the syntax used to define API types, their fields, relationships between types, and the entry points for queries, mutations, and subscriptions.

What You'll Learn

• SDL syntax for type definitions
• Field types, arguments, and nullability
• Defining relationships between types

Why It Matters

The schema is the contract between client and server. A well-designed SDL makes your API intuitive, self-documenting, and type-safe. DodaTech uses SDL to define all GraphQL API schemas.

Code Examples

# Basic SDL type definitions
type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  createdAt: DateTime!
  posts: [Post!]!
}

type Post {
  id: ID!
  title: String!
  content: String!
  published: Boolean!
  author: User!
  comments: [Comment!]!
  tags: [String!]!
}

type Comment {
  id: ID!
  text: String!
  author: User!
  post: Post!
}

# Custom scalar
scalar DateTime

# Root types
type Query {
  user(id: ID!): User
  users(limit: Int = 10): [User!]!
  post(id: ID!): Post
  search(term: String!): [SearchResult!]!
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

type Subscription {
  userCreated: User!
  postPublished(postId: ID!): Post
}

# Input types for mutations
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

input UpdateUserInput {
  name: String
  email: String
  age: Int
}

# Union and interface types
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
  content: String!
}

union SearchResult = User | Post

// SDL in code-first GraphQL (TypeGraphQL)
import { ObjectType, Field, ID, Int } from 'type-graphql';

@ObjectType()
class User {
  @Field(() => ID)
  id: string;

  @Field()
  name: string;

  @Field()
  email: string;

  @Field(() => Int, { nullable: true })
  age?: number;

  @Field(() => [Post])
  posts: Post[];
}

Common Mistakes

1. Not Using Input Types for Mutations

Using the same type for queries and mutations can expose fields that should not be writable.

2. Overusing Nullable Fields

Nullable fields complicate client handling. Make fields non-null when they always have a value.

3. Ignoring Naming Conventions

Use camelCase for fields, PascalCase for types. Consistent naming improves readability.

4. Creating Circular References Without Care

Circular type references can cause infinite resolution. Use DataLoader and limit query depth.

5. Not Documenting the Schema

Use comments and descriptions in SDL for auto-generated documentation.

Practice Questions

1. What does the ! symbol mean in SDL?
2. What is the difference between type and input type?
3. How do you define a relationship between two types?
4. What is a union type used for?
5. How do you define custom scalars?

Answers:

1. Non-nullable. The field will always return a value.
2. Input types are used for mutation arguments; regular types are for query responses.
3. Add a field on one type that returns the related type.
4. To represent a field that can return different object types.
5. Use the scalar keyword followed by the custom type name.

Challenge: Design a complete GraphQL schema for an e-commerce platform with users, products, orders, and reviews. Include types, input types, enums, interfaces, and root types.

FAQ

Mini Project

Build a GraphQL schema for a blogging platform. Include types for User, Post, Comment, Tag, and Category. Define relationships, input types for mutations, enums for post status, and a SearchResult union type.

What's Next

Deep dive into GraphQL object types and field resolution, then explore custom scalar types for domain-specific data.