Skip to content

Make "Schemas and Types" page more approachable to newcomers #1794

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 3 commits into from
Closed

Make "Schemas and Types" page more approachable to newcomers #1794

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7896b72
Update schema.mdx
jonathanberger Oct 11, 2024
6e23c01
Update schema.mdx
jonathanberger Oct 12, 2024
d06f813
Apply suggestions from code review
benjie Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions src/pages/learn/schema.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,16 +67,7 @@ Arguments can be either required or optional. When an argument is optional, we c

## The Query and Mutation types

Most types in your schema will just be normal object types, but there are two types that are special within a schema:

```graphql
schema {
query: Query
mutation: Mutation
}
```

Every GraphQL service has a `query` type and may or may not have a `mutation` type. These types are the same as a regular object type, but they are special because they define the _entry point_ of every GraphQL query. So if you see a query that looks like:
Every GraphQL schema must support `query` operations, the _entry point_ for these operations is a regular object type that by default is called `Query`. So if you see a query that looks like:

```graphql
# { "graphiql": true }
Expand All @@ -99,9 +90,18 @@ type Query {
}
```

Mutations work in a similar way - you define fields on the `Mutation` type, and those are available as the root mutation fields you can call in your query.
Schemas may also choose to support `mutation` operations by adding another entry point type, by default called `Mutation`. Mutations work in a similar way to queries - you define fields on the `Mutation` type, and those are available as the root mutation fields you can call in your mutation operation.

It's important to remember that other than the special status of being the "entry point" into the schema, the `Query` and `Mutation` types are the same as any other GraphQL object type, and their fields work exactly the same way.
It's important to remember that other than the special status of being the entry points, the `Query` and `Mutation` types are the same as any other GraphQL object type, and their fields work exactly the same way.
Copy link
Member

@benjie benjie Oct 17, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had already been confused why this special word schema was being used without being fully explained anywhere else on the page, so I took out the example that used it.

I see what you mean; it's introduced a little to early. But since we talk about naming things by default maybe it's best to reintroduce the schema keyword at the end of this section detailing what you need to do if you don't want the defaults:

Suggested change
It's important to remember that other than the special status of being the entry points, the `Query` and `Mutation` types are the same as any other GraphQL object type, and their fields work exactly the same way.
It's important to remember that other than the special status of being the entry points, the `Query` and `Mutation` types are the same as any other GraphQL object type, and their fields work exactly the same way.
You can choose to name your entry point types differently; if you choose to do so then you will need to inform GraphQL of the new names using the `schema` keyword:
```graphql
schema {
query: MyQueryType
mutation: MyMutationType
}
```

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What percent of users would you estimate rename their entry points?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hard to say; but our very own swapi-graphql example API does: https://graphql.org/swapi-graphql/?query=%7B__typename%7D


You can choose to name your entry point types differently; if you choose to do so then you will need to inform GraphQL of the new names using the `schema` keyword:

```graphql
schema {
query: MyQueryType
mutation: MyMutationType
}
```

## Scalar types

Expand Down