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:

Caption: The fact that GraphQL schema != JSON Schema will go down as one of history's great misses. Forced me to create a JSON Schema-to-AppSync GraphQL compiler. Curious...anyone else doing work in this area?

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):

  1. GraphQL does not only deal with JSON, nothing stops a GraphQL API Β from delivering responses using a binary format like Protobuf for example. [1] 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.
  2. 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)).
  3. 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 πŸ‘‹

Enjoyed the post? Subscribe to Production Ready GraphQL!