Chapters 2,3 - reorder and change titles

[rivantsov]

Current Arrangement

Problem

1. The Language chapter - 11 out of 12 sections describe the Request language, that is about querying against the server's type system that is NOT DESCRIBED YET - it is the subject of chapter 2. You literally have to jump forward and back (pic) It seems more logical to describe type system first, then how to make requests against it

2. It might seem that 'Type System' would have no 'language' stuff, but - there is a lot of 'language' there! It defines the IDL (SDL).

Observation

Indeed we have 2 languages in GraphQL:

1. IDL/SDL
2. Request language

They are similar, share some elements, but still different languages - their domains do not intersect (for a doc - it is one or another).

Suggestion

New chapters order and titles:

1. Type System and Schema Definition Language (SDL)
2. Request Language

Additional consideration: section '2.1 Source Text' in current version describes basic language elements and its lexic base (terminals). It is common to both languages (SDL and Request).
In new arrangement, if we move the whole chapter it will end up in odd place - in the Request Language chapter (renamed from Language), after 'Type System and SDL'. It should retain the first position as it describes the common elements of languages. Maybe make it a separate chapter preceding these two? It is large enough to be a chapter.

[rivantsov]

@leebyron @benjie @IvanGoncharov @BoD @twof @michaelstaib @sachee @fotoetienne @yaacovCR @joeynenni
and everybody else
Kindly inviting to discussion and requesting feedback on this important subject.
Thank you!

[nodkz]

I agree that the chapter may be reordered.
But in such a case chapters 3,4,5 should be moved together because they describe server-side stuff:

---

After my talks, I'm tired to explain to people that GraphQL has two languages – SDL (for schema definition and development) and query language (for runtime).

Also, it will be nice to choose the exact terminology:

• SDL or IDL
• Query Language or Request Language

[rivantsov]

Hi, @benjie sorry for late response, was away for a while
why did you see that I meant "over-HTTP"? 'on the wire' was just a short and simplified ref to 'communication channel' that transmits the GraphQL query text and response. I am well aware that there are cases when both client and server (service) components run in the same process on the same machine, and communication channel is just direct call from client to server. That's the case for Teams, and from speaking with my friends there - they still use terms client and server even when of course they know it's not over HTTP; these are just convenient shortcuts.

GraphQL is more of an execution engine and query language.

Bang! query language! that's the term I would be happy with, much better than 'executable language'. But a bit misleading, since inside this language we distinguish queries, mutations, etc, would be a bit confusing. We started using 'request' term as a box for both, so Request Language seems still perfect name for it.
As for 'GraphQL is execution engine' - still do not see it this way. Do we ship the engine? No. WG publishes spec; other people build conforming execution engines.

[benjie]

As for 'GraphQL is execution engine' - still do not see it this way. Do we ship the engine? No. WG publishes spec; other people build conforming execution engines.

The GraphQL Specification is a specification that defines a "query language and execution engine". The "query language and execution engine" that the GraphQL Specification specifies is called "GraphQL". "GraphQL" is a query language and execution engine. The first sentence of the GraphQL Specification states as much:

This is the specification for GraphQL, a query language and execution engine [...]

[rivantsov]

yeah, you are right, it states "This is the specification for GraphQL, a query language and execution engine [...]".

But it also states:

GraphQL is a query language designed to build client applications

so, what is it? The problem is that both of these are very problematic and referencing either of them for judgement on other issues is very problematic as well. The other discussion about formal GraphQL definition is aiming to fix that.

[twof]

I feel like saying it's confusing to just call GraphQL a query language without mentioning the executor is like saying it's confusing to call C++ a programming language without mentioning the compiler. Obviously there's a compiler. The details of the compiler don't actually matter to most people because most people are just trying to write some C++. If my audience was C++ compiler developers I might also mention the fact that C++ is processed by compilers, but I don't think it would be wrong to omit that fact.

Perhaps considering the audience of the spec would be helpful. If we expect it to primarily be read by implementers, unconcerned with the use case of the things they're building, then maybe stripping out every mention of the historical and real world majority use case of GraphQL is a valid course of action. If that's not the expected audience of the spec, then maybe we don't do that. It could also be that different parts of the spec have different audiences, and the precision required in the Execution section isn't also required in the Overview section.

I'd also like to point out that the passage you're quoting could be speaking of history. GraphQL was literally designed to build client applications. That's not incorrect. It's now used for other things, but providing context for the purpose it was designed for is helpful.

Furthermore I feel that this whole discussion of "what is GraphQL exactly?" isn't particularly useful, and it's quite resource intensive. On the level of "Is a hotdog a sandwich". We're all touching different parts of the elephant.

[rivantsov]

Well, strangely this thread deviated from the original subject, which was - naming the chapters and finding a convenient, clear term for part of GraphQL language that is used for formulating requests (vs other part which is for describing schemas). The term, name of sublanguage (Request Language, Executable Language?) - does not need to be precise, or pin-pointing the philosophical question "What is GraphQL?" (we have a separate discussion for this). Just a convenient name, in context of 2 chapters, since each chapter defines its own sub-language.

As for your reference to the 'Elephants' story, I do not think it works here at all. The blind men did not 'create' the elephant, or did not draft a spec for it. It was external thing, and of course personal impressions differ. We, the WG, on the other hand, we DEFINE the thing - GraphQL, and we must be precise and detailed about the thing we define (and control to some extent). Starting with basic definition "GraphQL is ...".

We cannot say: well, what is GraphQL it's different thing for different people, opinions differ, and we are OK with anything, whatever. Everybody is entitled to his/her own beliefs. We cannot do that.

GraphQL was literally designed to build client application.

Well, if it was a client application without server part? There were no Facebook GraphQL servers at the time, GraphQL was just client-side thing?

Furthermore I feel that this whole discussion of "what is GraphQL exactly?" isn't particularly useful, and it's quite resource intensive.

I feel exactly opposite way. To create a spec for something without defining what it is - sounds really silly. And many of the discussions and disagreements here and around GraphQL come from this absence of clear definition and 'scope'.