With that massive release note out of the way…
I’ve been working a with Json Schemas for a couple of weeks and even though it feels like XML all over again they are really useful. In a world of microservices receiving commands and/or events from queues it can be hard to communicate the structure of the json on the wire without a formal language.
Json Schema is that formal language.
I won’t even pretend to know the inner workings of Json or Json Schema but I have found some things that might be useful for anyone else just starting to look at it.
The first thing that hit me was that it takes a long time to write a schema if you have to go through unit tests to observe the result of your editing. I started out using jsonschemavalidator.net and it worked quite well for my initial testing. I did hit a brick wall when I started to use json that was more in line with what I would see in production and I wasn’t sure if my test data needed some security clearance. Better safe than sorry, so instead of sending potentially secret data to an unknown receiver I made the tool announced above to locally validate json against a schema. (no the test data I worked with was not a GDPR issue) Since then I have had to validate json while finding errors in acceptance test and really appreciated it.
My first take on validating json in our application was to use Newtonsoft but I didn’t read the licensing note as well as I should have so the 1000 items per hour limit in their free offering hit me hard when integration testing with realistic amounts of data. $999 isn’t much for my organization but I figured dragging a purchase order through the ranks would take longer than I could afford at the moment.
When looking for something else to validate our json i found Manatee.Json that worked like a charm in my test environment. It might be a configuration issue, but I found Manatee.Json to have a lot better messages for diagnosing failing validations compared to Newtonsoft. The Manatee.Json solution made it out to production without me doing any real performance tests. That neglect came right back at me within a day. Manatee.Json was way to slow in validating our larger messages.
I got the purchase order through the ranks so now we are using Newtonsoft for the initial validation. If I find validation errors I do the validation again using Manatee.Json to get the nicer validation error messages.
Since Manatee.Json is open source I took a look at its code and found a couple of things that will make it a bit faster when validating against a schema. Not the factor of ten needed to compete with Newtonsoft in our scenario, but it’s a nudge in the right direction. While having the pull request dialog I got some really useful advice from gregsdennis regarding our schema.
Now that we have the schema validation in place our cross team json structure discussions are no longer made with ambiguous examples floating in emails. So a check mark for that.
… now there’s just the little detail called schema versioning we have to figure out.
As a side note: It you’re using UnionWith to populate an empty HashSet