Hi all,

Typing to you from an airport in the UK, I'm on my way to talk about JSON Schema in Canada for the API Specification Conference 2019 (ASC2019). We spent the last year and a half, give or take, working on the latest draft of JSON Schema, draft 2019-09. It's had its ups and downs, and it's been pretty challenging at times, but we've made it, published it, and now it's out there waiting for implementers to get stuck in once again.

---

See end of post for sponsorship information.

---

The "new" JSON Schema core team started back in 2015, and have thrown themselves in to updating JSON Schema to cope with new and unexpected uses, and tackle some really tricky and difficult to understand concepts.

I've been part of the current core team since its 2015, and we're now nearly FIVE years later. The team has grown a little, and it's been great working with such talented people on JSON Schema.

Austin did a fantastic job taking point in the first few drafts, fixing things which clearly had become issues since draft-4, and adding new powerful keywords to make JSON Schema better than it was before. He dramatically improved the readability of the spec, laying important groundwork for future improvements.

Henry has worked relentlessly on ironing out long-standing rough edges, tackling some of the most difficult issues, and fixing many of the most common wish list and pain point items.

As a collective, we've taken a LOT of time to listen to your feedback, and support you, the community, as much as we can. We set up a slack, which is open to anyone. We look at Github issues across many implementations in case we can help out. We even track StackOverflow questions for the json-schema tag. We debug schema issues on slack on an almost daily basis. This sort of quick feedback and support loop didn't work well as a Google Group, but the group is still there, should you want to use email.

For me personally, a lot has changed since forming the core team. I've taken an approach to fill in where I feel I can best serve the project and the community, doing a lot of admin work, and reviewing issues and PRs. I reached the point some years ago where it really registered that I'm part of the team that makes JSON Schema possible, and it fills me with pride to be able to share it with anyone who's interested.

I'm finding this an exciting crossroads in terms of moving forward with JSON Schema. Both Austin and Henry have done huge amounts of work, and of course we can't forget the epic levels of work from Julian continue to maintain and update the test suite with every draft. Recently, Greg Dennis has joined the authoring team, delivering “output” this draft. After discussion with the team and others more broadly involved, it feels like the right time for me to step up my involvement as a nominal lead, and take JSON Schema on the path out of draft land.

I feel privileged to share with you that this path is already starting to form. One of the early challenges we experienced when trying to work out how to take JSON Schema to standardisation was awareness and advocacy. I won't go into details, but we were met with a disappointing response from one standards organisation, which didn't spur us to try harder. At the time, we were already stretched thin, and felt best to re-focus on spec work and worry about the path to standardisation at a later date.

We need advocates and champions from different projects, sectors, and companies to affirm and support the “new” core team. It isn't enough that OpenAPI’s forthcoming 3.1 specification is adopting our latest draft, or that an earlier draft is baked in to 2019's most popular IDE / Text Editor, VSCode. No. We need to build up an image of legitimacy through connecting with people and being visible as a team and a project.

Earlier this year I applied to speak at a conference: ASC. I figured I'd spread my bets and submit two proposals, and maybe one would be accepted. Now I'm giving two talks tomorrow, and I was invited to join the conference committee, reviewing others proposals.

In addition, I recently set up the official Open Collective for JSON Schema. Open Collective is a platform for projects and causes to raise donations or funding from individuals or organisations in order to openly fund and be accountable in terms of how money is spent.

With just a small conversation with a few friends and colleagues, we have our first two sponsors. This allows me, and others in the team should they wish, to speak at conferences without cost to us individually. (Did I mention, since 2015, most JSON Schema has been unfunded?)

Stoplight and the AsyncAPI Initiative combined bring our annual budget to an estimated $4k. This makes me super excited about the future of JSON Schema. JSON Buddy has also become a financial contributor which is also encouraging.

Currently, were looking for any immediate feedback or issues with the new draft, just in case we missed something important. Our initial focus is updating the test suite for implementers. The team have already done a great job, and implementers and members of the wider community have already submitted back improvements.

I haven't shared in much detail my suggestions for plans moving forward with the team, but I'll be sharing some plans during one of my talks today. None of this is set in stone, and I want our decision process to be open and collaborative. I'll be creating a new governance and policy repo to handle this sort of process.

I want us to spend a little time working on educational resources and the website.

The website has gone long neglected. Not to say we haven't made some updates, and we even ingested the "understanding JSON Schema" website from the Space Telescope Science Institute, but we haven't done enough to clean it up, or consolidate learning resources from the main site and the "understanding" site. Huge props to Michael Droettboom (@mdboom) for keeping check and working on the migrated site!

I want us to create an official linter. The foundational work to make this happen has already been done and made opensource by Stoplight. Their linting tool, spectral, gives us the perfect foundations to work with code wise. While we have all written many schemas, we haven't created any such recommendations that would fall under a linter. JSON Buddy comes packed with a linter, so we certainly should look at how we can leverage existing linting definitions and rules into a common linter.

And of course, the path to standardisation.

This is still a little foggy for me, and I've probably had the most involvement in investigating our options.

Previous attempts to get the ball rolling, as I've mentioned, have left us feeling deflated. Some potential options have seemed JUST out of reach. This comes back to how JSON Schema needs to have broader recognition of an active and willing team, and well connected advocates. It's in the works, and there are people I plan to talk to even today to discuss this sort of thing, but my feeling is we aren't looking to complete in 2020 realistically.

We have work to do, and often do this during evenings and weekends. It's sometimes challenging to stay motivated, and sometimes conflict or difficult comments from the community really make it harder to keep active. Despite this, my hope is that draft 2019-09 is now like the baked cake, ready to have icing applied. We've done a lot of work, applied pressure, and it's practically there, but needs finishing to make it presentable.

Once the talk recordings are up, I'll update this post with the links, which includes a session on some new aspects of draft 2019-09, which is a real game changer for implementations which go beyond just validation.

Since draft-04, JSON Schema has become a foundational technology to multiple aspects of software design, way beyond what was originally conceived. Not just validation, but now class generation, form and UI generation, and even in editor suggestions for JSON and YAML files. 

Vocabularies for JSON Schema suddenly allows additional use cases to become interoperable by reliably and dynamically declaring the implementations support for understanding specific sets of keywords. We would particularly like feedback on the vocabulary concept, as its final form will depend on what we hear now from implementers and users.

If you've come this far, I really hope you'll be able to stick around and help us make JSON Schema even more useful than it is already. Come by our open slack or raise an issue where you see one. Ask questions on StackOverflow. I find it personally rewarding to help the community get stuff done. Let's keep allowing that to be possible for the whole community.

Cheers

Ben

-- Update post ASC2019

Wow, that was a fun ride. Two talks delivered, and taking part in a section of a panel.

Met some great people and I look forward to continuing to build those new friendships.

It feels like the talks were well received, and people had questions later, which shows at least a few people were listening.

Thanks, and hope to see you all again soon!

---

JSON Schema Open Collective: https://opencollective.com/json-schema

My personal support channels:

https://github.com/sponsors/Relequestual

https://ko-fi.com/relequestual

This update is cross-posted on the above supporter platforms.

Photo by Fleur on Unsplash