JSON Schema draft 2019-09 feedback and progress

Published on January 24, 2020 by Ben Hutton

If you've had an eye on the JSON Schema project over the past few years, you'll have seen the team work their socks off to make releases happen. 2019-09 was no different, and although the spec and meta-schema were released, we still have plenty of work to be done.

JSON Schema that Open API 3.1 will support full JSON Schema draft 2019-09!

In addition JSON:API 1.1 will support referencing both JSON Schema or OpenAPI description documents!

It's really difficult to remember that JSON Schema is still a "draft", meaning there's stuff we still haven't figured out how it works best. We conceptualise and bring new ideas to fruition with much consideration to the community already using JSON Schema and those brave people who turn the specification into code... BUT it's still impossible to really know the impact or practicalities till someone writes code for real world applications.

Since the current team took over some 5 years ago, we've lacked the industry connections to get feedback from large scale organisations. We've worked a little on this, but the main route has been the last years interaction with the Open API Initiative.

The whole JSON Schema team made this possible, but Henry Andrews and Phil Sturgeon did a LOT of the heavy lifting with OAS discussions and meetings from our side. How many PRs have you see that close FIFTEEN related issues in one go?

https://github.com/OAI/OpenAPI-Specification/pull/1977

Being able to present and talk through all the changes made for draft 2019-09, and have it accepted to replace an existing subset superset, is very validating of all the hard work.

From the OpenAPI side, thank you so much to Ron, Darrel and Ted. It's been a long road but we made it.

Our next step is to make some clarifications to the JSON Schema specification, fixing a number of potentially confusing or unclear elements picked up on by OAS people. We're tracking these issues, lovingly collated by Henry, at https://github.com/json-schema-org/json-schema-spec/milestone/8 as "draft-08-patch1".

This will result in new draft documents, but with no change to the meta-schema or specification defined functionality.

We're also working on making sure we have enough tests for implementers to be sure of their implementation. Greg has done a fantastic job of breathing life into the first draft 2019-09 implementation of JSON Schema, and Julian has been wrangling tests and making sure every single change is correct. Greg followed the approach of having running code, working on defining the standardised output format for draft 2019-09 and at the same time working on his updated implementation.

I've also personally been working on making improvements to https://jsonschema.dev , which now supports generating actual short URLs! Go crazy! Next is a refactor... time to pay that technical debt from building it as an MVP.


Finally, a note from Henry and I. We are both currently open to taking on consulting opportunities. Henry is open for OpenAPI and JSON Schema related consultation. I am only open for JSON Schema consultations right now. You can view Henry's credentials at https://www.linkedin.com/in/handrews/ and mine at https://www.linkedin.com/in/benhuttonuk

Henry is based in the US, while I'm based in the UK.

Reach out to Henry: [email protected]

Reach out to Ben: https://calendly.com/jsonschema/lets-talk


That's all for now, but stay tuned for progress reports of work on draft 2019-09 patch 1 and the 2019-09 tests.