As I was writing the initial draft of this post, I started a big discussion about how best to format the specifications for declarations of Work, Protocol Negotiation, and Diplomatic Agents (collectively called Diplomatic Markup Language, or DML). I based this discussion on my biased views of XML, JSON, and YAML. My initial concern was the ability to validate schema. I knew I could do that easily in XML. In fact, that’s one of the main reasons I still reluctantly tolerate XML. But then I figured I should probably do some research. Just because I had never heard of a way to validate JSON or YAML did not mean that there was no such thing in place.

My search first turned up JSON Schema. It looked promising but after spending ten minutes slogging through a bunch of technical documentation, I was unimpressed. Next I found some interesting libraries for YAML (some of which also supported JSON). My cursory review did not turn up anything that seemed to be in active development. Still, I did not give up. After digging a bit more, I stumbled on an excellent blog post about using YAML schema to validate YAML files.

Lars Lockefeer explained how they did it at Picnic. His example used one of the libraries I had looked at but did not seem to be in active development. I read the article anyway because it was interesting and well-written. At then end, he mentioned JSON Schema for anyone who was “excited” by the topic. So I gave it another shot.

I went back the JSON Schema site and browsed a list of implementations. I found two written in PHP and checked them both out. The second one I looked at had me hooked. Opis JSON Schema had an update just two months ago, but it was really the documentation that had me sold. They covered both the JSON Schema itself as well as how to use their API. If there were such a nice, simple, clear guide on the JSON Schema site, I could have saved myself a bunch of time.

Anyway, long story short. There’s no question for me. Specification formats need to be in a format that’s widely adopted and recognizable. They should be validatable using well-defined schema. They should not be verbose. And lastly, whitespace should not be a tool for defining elements but a tool that allows you to adopt an aesthetic preference. JSON wins hands down on all counts.

My next post will cover first thoughts about Work Declaration. DŌP’s about to get real.