Make "Schemas and Types" page more approachable to newcomers

[jonathanberger]

I'm new to GraphQL so I may be mistaken but I believe the author intended to capitalize the type names in this passage since they are capitalized in the paragraphs below. The capitalization is important to get right in this context since the example right above the changed text has both "query" and "Query" in it.

[vercel]

@jonathanberger is attempting to deploy a commit to the The GraphQL Foundation Team on Vercel.

A member of the Team first needs to authorize it.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: jonathanberger / name: Jonathan Berger (7896b72, 6e23c01)
• ✅ login: benjie / name: Benjie (d06f813)

[jorydotcom]

Thanks for contributing, @jonathanberger ! Can you sign our CLA?

[benjie]

Hi @jonathanberger; thanks for your contribution! These terms can be overloaded quite heavily, making it confusing; I did some work on the spec to stop us using the word query in so many ways: graphql/graphql-spec#715

I believe that the text here is not (contrary to what it says) referring to a Query type, but instead saying that there must be a type (it can have any valid name) that's used for the "query operation". We now call this the "root operation type" for the query operation: https://spec.graphql.org/draft/#sec-Root-Operation-Types

e.g. this is a valid schema:

type Query {
  a: Int
}

This is also a valid schema (note it does not have a Query type, but it does have a type for the query operation, called Root):

schema {
  query: Root
  mutation: Changes
}
type Root {
  a: Int
}
type Changes {
  b: Int
}

This is also valid (but super confusing!):

schema {
  query: Mutation
  subscription: Query
}
"""The query root operation type in this schema"""
type Mutation {
  a: Int
}
"""The subscription root operation type in this schema"""
type Query {
  b: Int
}

I agree the text you've found is confusing; would you like to submit an improved fix that factors in this knowledge?

[jonathanberger]

Benjie, thanks so much. That really help clarifies. I took a crack at updating the docs to what I think I would have wanted before wading into this and understanding it a bit more. I realize I'm cutting out an example that is there today, but I think it's a beneficial simplification that will ease the GraphQL learning curve.

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.

[benjie]

This documentation is significantly out of date, we've not even mentioned subscriptions for example. I've taken a slightly alternative approach, what do you think?

[benjie]

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
	}
	```

[jonathanberger]

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

[benjie]

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

[benjie]

@jonathanberger I still would like your feedback on that last point, but I've gone ahead and committed the changes since there is overlapping work in #1800

[jonathanberger]

I think your latest approach is an improvement. Thanks!

[benjie]

Awesome; your work has been incorporated into #1800 so I'm going to close this PR - thanks again @jonathanberger 🙌