Hey 👋 Long time no see. I haven't posted a lot lately because everything I write ends up in the book, which you should subscribe for if you haven't already :D.
Anyways, this is a first in a new series of post I've been wanting to do for a while: "GraphQL Head Scratchers". Once in a while I see certain takes on GraphQL (positive or negative) that are real strange to read. When I see some of them and if they have the potential to bring good reflections I'll try to make a post out of them.
So here we go, the GraphQL Head Scratcher #1:
Interesting argument in this tweet. Should the GraphQL authors simply have decided to use JSON schema to describe a GraphQL API?
There are many things to talk about here. First what exactly is JSON Schema? Let's get that out of the way:
JSON Schema is a vocabulary that allows you to annotate and validate JSON documents.
Here's a few reasons why GraphQL's type system cannot simply be described by JSON schema (without an extended vocabulary of some sort):
- GraphQL does not only deal with JSON, nothing stops a GraphQL API from delivering responses using a binary format like Protobuf for example.  Sure JSON is probably the most common out there, but using JSON schema to describe non-JSON objects get a bit whacky.
EDIT: Phil Sturgeon corrected me on twitter, JSON schema can indeed be used to describe other structures like YAML.
- While a GraphQL schema describes the possibilities that are queryable by a client at runtime, it is very hard, by design, to describe ahead of time the exact shape of a response. Describing that behavior with JSON schema would be incredibly verbose (something like any_of(all_selection_possibilities)).
- JSON Schema at its core is not necessarily about APIs, it's about describing JSON data models. A better comparison would be GraphQL & OpenAPI, ways to describe not only the response shapes of an API but describing how to interact with it. (Think for example about directives, and field arguments).
Given these 3 points, I do not think that coming up with the GraphQL schema / type system was a monumental mistake, and I would be highly surprised if the JSON Schema specification would want to deal with GraphQL concerns in the first place.
What do you think? Let me know 👋