GraphQL Schema Fundamentals

# CHAPTER 5

GraphQL Schema Fundamentals #

1. Introduction #

2. Learning Objectives #

• Explain what a GraphQL Schema is and why it is necessary.

• Read and write GraphQL Schema Definition Language (SDL).

• Define custom Object Types and their corresponding fields.

• Understand the concept of "Root Types" (Query, Mutation).

• Architect a basic, real-world schema structure.

3. Beginner-Friendly Explanation #

In GraphQL, the Schema is your blueprint.

• You define Types (the rooms): e.g., a User, a Product.

• You define Fields (what's inside the rooms): e.g., name, price, email.

• You define the Root Query (the front door): How do people enter the house to find the rooms?

Because of this strict blueprint, the frontend developer knows *exactly* what they can ask for without ever having to guess or look at PHP database code.

4. Real-World Examples #

• The Library App: If you are building an API for a library, your schema would define a Book type, an Author type, and a Member type. The schema explicitly states that a Book has a title (String) and an author (which points to the Author type).

• Auto-generating Documentation: Because the schema acts as a strict typing system, tools like Apollo Explorer automatically read the schema and generate beautiful, clickable documentation for your API. You never have to manually write API docs again!

5. Detailed Code Examples #

Defining Types using SDL:

# This defines a custom object type
type User {
  id: ID!
  username: String!
  email: String!
  age: Int
  isActive: Boolean
}

# The Root Query is how clients fetch data
type Query {
  # Field name: returns a single User
  getUser(id: ID!): User
  
  # Returns a list of Users
  getAllUsers: [User!]!
}

*(Note: The ! exclamation mark means the field is required and cannot be null.)*

6. Query Examples #

query {
  getUser(id: "123") {
    username
    isActive
  }
}

7. Mutation Examples #

In the Schema:

type Mutation {
  createUser(username: String!, email: String!): User
}

The Client's Execution:

mutation {
  createUser(username: "johndoe", email: "john@example.com") {
    id
    username
  }
}

8. Schema Examples (PHP vs SDL) #

schema.graphql

type Post {
  title: String!
  content: String
}
type Query {
  latestPost: Post
}

PHP Loading SDL:

<?php
use GraphQL\Utils\BuildSchema;

$contents = file_get_contents(&#039;schema.graphql');
$schema = BuildSchema::build($contents);
// You can now execute queries against this schema!
?>

9. Best Practices #

• Design the Schema First: Embrace "Schema-First Design." Before writing any PHP or frontend code, backend and frontend developers should sit down, agree on the Schema SDL, and save it. Both teams can then work independently.

• Use Descriptive Names: Name your fields clearly. Use camelCase for fields (firstName) and PascalCase for Types (UserProfile).

• Use Comments: You can add descriptions to your schema using quotes (""). This populates the API documentation.

"""
Represents a registered customer on the platform.
"""
type Customer { ... }

10. Common Mistakes #

• Forgetting Required Flags (!): If you know an ID or a Name will *always* exist in the database, mark it with !. If you don't, frontend developers have to write unnecessary null-checking code.

• Leaking Database Structure: Don't just copy your MySQL tables 1:1 into GraphQL. The schema should represent the *business logic* and how the UI needs the data, not how the database stores it.

11. Mini Exercises #

1. 1. Look at this SDL: type Movie { title: String!, rating: Float }. Is the rating required or optional?

1. 2. Write a schema definition for a Song that has an id, a title, and a duration in seconds.

1. 3. Define a Root Query that allows fetching a list of Songs.

12. Coding Challenges #

13. MCQs with Answers #

14. Interview Questions #

• Q: Explain "Schema-First Design" and why it benefits development teams.

• Q: How do you define a list/array of items in a GraphQL schema?

• Q: If you have an id field that should never be null, how do you write that in SDL?

15. FAQs #

Q: Do I have to write the schema in a .graphql file, or in PHP arrays? A: Either approach works. Writing it in a .graphql file (Schema-First) is generally preferred because it is easier to read and share with frontend teams.

16. Summary #

17. Next Chapter Recommendation #