Why Do People Dislike JSON?

Phil Sturgeon

Aug 26, 2017 — 3 min read

I’ve seen a few people promoting GraphQL and gRPC over REST, almost purely on
the merits of being "not JSON”. They moan about JSON and instil the virtues of
these architectures for their use of stricter type systems.

As well as blaming JSON for various imagined faults, they continue on to blame
REST for an entirely non existent reliance on JSON.

REST is a architectural concept, and doesn’t care what data format you use. A
REST API can receive and transmit data in any combination of JSON, XML, CSV,
images, videos, binary or lolcat. It really doesn’t matter.

As explained in You Might Not Need
GraphQL,
if you’re mainly interested in this specific feature, your REST API can
absolutely implement
Protobuf, Cap’n
Proto, or any other similar stricter type system.

I posted a tweet along these lines, and got a great question back.

Dislike of JSON

When you hear somebody stating their dislike for JSON, it usually stems from the
same thing: weak types. A field in JSON could be an integer in one instance,
string in another, object on another response.

It could change at any moment, even accidentally, and it could go unnoticed by
either client or server for a while. Some weakly typed languages like PHP don’t
really worry about it, as a 123 and a "123" are the same thing, but other
languages certainly do fall over.

To imagine the difference, think about data structures in programming languages.
When you type hint on "object” or "array” you have no idea what shape that data
will be, but if you hint against a specific class or interface name then you’ve
got some assurances. JSON is like an unnamed object/array, and a lot of people
don’t like things being that vague.

There’s also a lack of explanation about what a field could contain. If you’re
looking at a status field, you do not know what other values it could contain.

None of this has anything to do with JSON. This would be the same if you built
an API in XML or CSV, yet still people blame JSON.

Data by itself is vague. Data needs metadata. This concept isn’t new, it’s just
been ignored for a while, and it’s time to remember how things used to work.

Everything Has Happened Before

In the late 90's, people were building XML-RPC APIs with
arbitrary fields being sent up and down. There was not much explanation about
what anything was, and a string could change to an integer rather easily.

This was much worse in XML as everything is a string anyway, so XML Schema
(XSD) was developed to describe the
contracts. Humans and computers then knew which types which fields were expected
to be, and loads of expectations could be built around that.

XML Schema was one of the core concepts of SOAP, which people then started to
hate due to being overly complicated. They rushed to REST, with some people
trying to "fit the entire request in the URL” as a testiment to how simple REST
was.

If your idea of a good API interaction is
json_decode(file_get_contents("http://api.example.org/v2/something.csv")) then
you might need to read this
book.

Confusing REST for this oversimplified style of interaction, then blaming it for
tripping you up, is exceedingly daft.

devs be like

Everything Will Happen Again

JSON Schema is a similar tool to XML Schema. You can
design JSON Schema with UML-style
tools, use that JSON
Schema for documentation, mocking, response validation, and all sorts of other
things.

In REST this stuff is optional. You can use it if you want, or you can ignore
it. Even if you implement JSON Schema, nobody has to interact with it.

{
  "schema": "http://api.turtles.com/schemas/turtle.json",
  "id": "213-1398-fdsf",
  "foo": "bar",
  ...
}

That’s about it.

Or you can use Protobuf.

Or, you can still use JSON Schema and add a step in your build chain to
generate Protobuf contracts from JSON
Schema; Offering both
depending on the Content-Type header.

The world is your oyster once you write specifications.

The ecosystem for JSON Schema, specifications, documentation,
etc.,
is still ongoing and improving, but a lot of people are throwing the baby out
with the bath water and jumping into whole API rewrites for a benefit they could
easily have in their existing APIs.

Most importantly, let’s not confuse people by blaming JSON or REST for problems
that are nothing to do with either of them.