Why schema defines the API contract in GraphQL - Visual Breakdown

Concept Flow - Why schema defines the API contract

Client sends query

↓

Schema validates query

↓

Schema defines types & fields

↓

Server executes query

↓

Response matches schema

↓

Client receives data as promised

The schema acts like a promise between client and server, defining exactly what data can be asked for and what will be returned.

Execution Sample

GraphQL

type Query {
  book(id: ID!): Book
}
type Book {
  id: ID!
  title: String
}

This schema defines a query to get a book by ID, specifying the fields the client can request.

Execution Table

Step	Action	Input/Query	Schema Role	Result/Output
1	Client sends query	{ book(id: "1") { id title } }	Schema defines 'book' query and 'Book' type	Query accepted, fields 'id' and 'title' valid
2	Schema validates query	Check if 'book' exists and fields requested are valid	Schema confirms 'book' and fields exist	Validation passes
3	Server executes query	Fetch book with id=1	Schema guides data shape	Data fetched: { id: "1", title: "GraphQL Basics" }
4	Response sent to client	Data matches schema shape	Schema ensures response matches contract	Client receives { book: { id: "1", title: "GraphQL Basics" } }
5	Client uses data	Data matches expected types and fields	Schema contract fulfilled	Client can safely use data
6	Query with invalid field	{ book(id: "1") { id author } }	Schema rejects unknown field 'author'	Error returned: Field 'author' not found on type 'Book'
7	Exit	No further processing	Schema enforces contract	Execution stops due to validation error

💡 Execution stops when query fields do not match schema, ensuring API contract is enforced.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	Final
query	null	{ book(id: "1") { id title } }	Validated	Executed	Response formed	Used by client
schema	Defined	Used to validate query	Used to check fields	Used to shape data	Ensures response matches	Enforces API contract
response	null	null	null	{ id: "1", title: "GraphQL Basics" }	Sent to client	Received and used

Key Moments - 2 Insights

Why does the schema reject a query with a field not defined in it?

Because the schema defines exactly which fields exist, any field outside this is invalid, as shown in execution_table row 6 where 'author' is not in 'Book' type.

How does the schema help the client know what data to expect?

The schema specifies the types and fields, so the client can trust the response shape, as seen in rows 4 and 5 where the response matches the schema.

Visual Quiz - 3 Questions

Look at the execution_table, what happens at step 3?

A The client sends the query to the server

B The server executes the query and fetches data shaped by the schema

C The schema rejects the query due to invalid fields

D The client receives the response

💡 Hint

Refer to execution_table row 3 where the server fetches data guided by the schema

At which step does the schema reject a query with an invalid field?

A Step 2

B Step 4

C Step 6

D Step 5

💡 Hint

Check execution_table row 6 where the invalid field 'author' causes rejection

If the schema did not define the 'book' query, what would happen when the client sends a query for it?

A The schema would reject the query during validation

B The query would be accepted and executed

C The server would return empty data

D The client would receive data with null fields

💡 Hint

Schema validation (rows 1-2) ensures only defined queries are accepted

Concept Snapshot

GraphQL schema defines the API contract.
It specifies queries, types, and fields.
Queries must match schema to be valid.
Schema ensures server response matches client expectations.
Invalid queries are rejected before execution.
This guarantees reliable communication.

Full Transcript

In GraphQL, the schema acts as a contract between the client and server. When a client sends a query, the schema first validates it to ensure the requested fields and types exist. If valid, the server executes the query and returns data shaped exactly as the schema defines. This process ensures the client receives data it expects and can safely use. If the query contains fields not in the schema, it is rejected immediately, preventing errors. This contract keeps communication clear and reliable.

Practice

1. What is the main purpose of a GraphQL schema in an API?

easy

A. To define the types of data and queries the API supports

B. To store user data permanently

C. To style the API responses with colors

D. To encrypt the data sent over the network

Solution

1. Step 1: Understand what a schema represents

   A GraphQL schema acts like a menu that lists what data and operations are available in the API.

2. Step 2: Identify the schema's role in API communication

   It defines the types and queries so clients know exactly what they can ask for and expect.

3. Final Answer:

   To define the types of data and queries the API supports -> Option A

4. Quick Check:

   Schema = API contract [OK]

Hint: Schema is the API's menu of data and queries [OK]

Common Mistakes:

• Thinking schema stores data permanently
• Confusing schema with styling or encryption
• Believing schema handles data encryption

2. Which of the following is the correct way to define a simple GraphQL schema type for a User with an id and name?

easy

A. type User { id: Int name: String }

B. type User { id: Int, name: String }

C. type User { id Int, name String }

D. type User (id: Int, name: String)

Solution

1. Step 1: Recall GraphQL type syntax

   Fields inside a type are defined with a name, colon, then type, separated by commas or new lines.

2. Step 2: Check each option's syntax

   type User { id: Int, name: String } correctly uses colons and commas to separate fields: id: Int, name: String.

3. Final Answer:

   type User { id: Int, name: String } -> Option B

4. Quick Check:

   Correct field syntax = type User { id: Int, name: String } [OK]

Hint: Use colon between field and type, commas optional but clearer [OK]

Common Mistakes:

• Omitting colons between field and type
• Using parentheses instead of braces
• Missing commas causing syntax errors

3. Given this schema snippet:

type Query { user(id: Int): User }

What will happen if a client queries for { user(id: 1) { id name } } but the schema does not define the name field on User?

medium

A. The query will return an error about the unknown field 'name'

B. The query will return the user with an empty 'name' field

C. The query will ignore the 'name' field and return only 'id'

D. The query will return null for the entire user

Solution

1. Step 1: Understand schema validation

   GraphQL validates queries against the schema. If a field is not defined, it causes an error.

2. Step 2: Apply to the given query

   The 'name' field is missing in the User type, so the query asking for it will fail with an error.

3. Final Answer:

   The query will return an error about the unknown field 'name' -> Option A

4. Quick Check:

   Query fields must exist in schema [OK]

Hint: Query fields must match schema exactly [OK]

Common Mistakes:

• Assuming missing fields return empty or null silently
• Thinking GraphQL ignores unknown fields
• Believing partial data is returned without error

4. You wrote this schema:

type Query { getUser(id: Int): User }

But your API returns an error when querying { getUser(id: 5) { id name } }. What is the likely mistake?

medium

A. The Query type must be named 'query' in lowercase

B. The query syntax is invalid because of missing commas

C. The argument 'id' should be non-nullable with an exclamation mark

D. The User type is not defined or missing fields

Solution

1. Step 1: Check schema completeness

   The Query type is correctly named with uppercase 'Query', which is standard in GraphQL.

2. Step 2: Consider User type definition

   If the User type is missing or lacks requested fields like 'id' or 'name', the query will error.

3. Final Answer:

   The User type is not defined or missing fields -> Option D

4. Quick Check:

   Missing type or fields cause query errors [OK]

Hint: Check if all types and fields exist in schema [OK]

Common Mistakes:

• Thinking Query must be lowercase
• Assuming nullable arguments cause errors
• Blaming query syntax when schema is incomplete

5. You want to extend your GraphQL API to include a new type Book with fields id, title, and author. How does defining this in the schema help your API users?

hard

A. It hides the Book type from users to keep it private

B. It automatically fills the database with book data

C. It tells users exactly what data they can request and how to ask for it

D. It encrypts the Book data before sending it

Solution

1. Step 1: Understand schema role in API design

   Defining a new type in the schema acts like adding a new menu item, showing users what data is available.

2. Step 2: Explain benefit to API users

   This helps users know what fields exist and how to write queries to get that data without errors.

3. Final Answer:

   It tells users exactly what data they can request and how to ask for it -> Option C

4. Quick Check:

   Schema defines API contract for users [OK]

Hint: Schema shows users what data and queries exist [OK]

Common Mistakes:

• Thinking schema fills or encrypts data
• Believing schema hides types from users
• Confusing schema with database content