JSON is robot barf. Don't get me wrong. JSON is a fine serialization format for data and I have no problem with it in that context. My beef is with the use of JSON for configuration files, policy specs, and so on. If JSON were all we had, then we'd have to live with it. But we've been building parsers for almost 70 years now. The technology is well understood. There are multiple libraries in every language for parsing. And yet, even very mature, well supported frameworks and platforms persist in using JSON instead of a human-friendly notation.

When a system requires programmers to use JSON, what they're effectively asking developers to use an "abstract" syntax instead of a "concrete" syntax. Here's what I mean. This is a function definition in concrete syntax:

And here's the same function definition expressed as an abstract syntax tree (AST) serialized as JSON:

I don't know any programmer who'd prefer to write the abstract syntax instead of the concrete. Can you imagine an entire program expressed like that? Virtually unreadable and definitely not maintainable. Parsing can take as much as 20% of the time taken to compile code, so there's a clear performance win in using abstract syntax over concrete, but even so we, correctly, let the machine do the work.

I get that systems often start out simply with simple configuration. Some inputs are just hierarchies of data. But that often gets more complicated over time. And spending time figuring out the parser when you're excited to just get it working can feel like a burden. But taking the shortcut of making developers and others write the configuration in abstract syntax instead of letting the computer do the work is a mistake.

I'd like to say that the problem is that not enough programmers have a proper CS education, but I fear that's not true. I suspect that even people who've studied CS aren't comfortable with parsing and developing notations. Maybe it's because we treat the subject too esoterically—seemingly useful for people designing a programming language, but not much else. And students pick up on that and figure this is something, like calculus, they're unlikely to ever use IRL. What if programming langauge classes helped students learn the joy and benefit of building little languages instead?

I'm a big believer in the power of notation. And I think we too often shy away from designing the right notation for the job. As I wrote about Domain Specific Languages (DSLs) in 2007:

I'm in the middle of reading Walter Isaacson's new biography of Einstein. It's clear that notation played a major role in his ability to come up with the principle of general relativity. He demurred at first, believing that the math was for someone else to come along later and tidy up. But later in his life, after the experience of working on general relativity, Einstein became an ardent convert.

Similarly, there is power in notation for computing tasks. Not merely the advantage of parameterized execution but in it's ability to allow us to think about problems, express them so that other's can clearly and unambiguously see our thoughts, and collaborate to create joint solutions. What's more, languages can be versioned. GUI configurations are hard to version. Notation has advantages even when it's not executed.

The DSL becomes the focal point for design activities. The other day, I was having a discussion with three friends about a particular feature. Pulling out pencil and paper and writing what the DSL would need to look like to support the feature helped all of us focus and come up with solutions. Without such a tool, I'm not sure how we would have communicated the issues or whether we'd have all had the same conception of them and the ultimate solution we reached.

As this points out, clear notations have advantages beyond being easier to write and understand. They also provide the means to easily share and think about the problem. I think system designers would be better off if we spent more time thinking about the notation developers will use when they configure and use our systems, making it clear and easy to read and write. Good notation is a thinking tool, not just a way to control the system. The result will be increased expressiveness, design leverage, and freedom.

Photo Credit: Sick Android from gfk DSGN (Pixabay)