JSON Schema Collaborators Summit in-person | May 8-9 2023, Vancouver

[benjagm]

Preamble

These notes are mostly unpolished notes from the first JSON Schema Collaborators Summit in-person two day meeting. Not all of the core collaborators were able to make it to the meeting. We value community feedback, as many of our community have great expereince and insight to share.
As such, the following are notes only, and do not imply or express any decisions made, and are instead as an opportunity for others to provide feedback, thoughts, and opinions on what was discussed. Using this feedback, we will provide a more full and polished write up, with further outcomes and suggested actions.
- Ben Hutton

Summary

JSON Schema was yet to have an in-person meeting. As an organization, we have evolved over the past few years into a different entity, and felt we would benefit from discussions and decisions made in person, which are, at best, difficult virtually.

The Linux Foundation is hosting a multi-community conference called Open Source Summit North America. The conference includes a track for the OpenJS Foundation, which is JSON Schema's foundational host.

The JSON Schema team is widely distributed, so meeting before the OSS NA conference was be convenient and beneficial. In addition, those attending the conference could take advantage of reduced hotel rates or travel funding from the OpenJS Foundation. Being a Linux Foundation member, we could additionally take advantage of reduced conference ticket rates.

Summit Details

• Location: In-person | Vancouver,Canada
• Dates:
  • Monday, May 8 (9:00 am – 5:00 pm PDT)
  • Tuesday, May 9 (9:00 am – 5:00 pm PDT)

Goals

• Discuss the current Status of JSON Schema Ecosystem.
• Build the project roadmap and long term vision.
• Define the requirement to incorporate projects to the organization.
• Identify skills gaps.
• Run a retrospective about the progress in the years.
• Plan for developing, expanding, and publishing linting rulesets.
• Spend time working together in-person.

Agenda

The detailed schedule is available here.

Day 1:

• Review the current state of JSON Schema and its ecosystem.
• Discuss project vision and create 5 year vision statements and a 12 month roadmap.
• Identify new team requirements based on the roadmap.

Day 2:

• Build the JSON Schema vision statement.
• Discuss critical path and requirements for onboarding specific tooling into the organization-
• Plan for developing, expanding, and publishing linting rulesets.
• Retrospective

Results

We organized the first in-person Collaborators Summit in Vancouver for the 2 days before Open Source Summit North America (2023-05-08 - 2023-05-09). Even though 2 days of summit plus 3 days of the conference is a lot, organizing the Summit the same week made it easier for team members to get OpenJS funding for their trip and conference ticket. It made it easier to justify costs to employers.

The final list of attendees was: @Relequestual , @gregsdennis , @jdesrosiers , @Julian and @benjagm.

During the Summit we needed to reorganize and adjust the agenda resulting in these independant discussions:

• Individual expectations.
• Status of JSON Schema Ecosystem.
• Roadmap and Vision.
• Identify skills gaps.
• Requirements to incorporate tools to the Organization.
• Linting tooling.
• Project Retrospective.

Individual expectations

We started the summit with an icebreaking activity with everyone sharing some of their individual expectations with the Summit:

• @benjagm Know everyone in person. Learn about the project. Align my work with the real project priorities.
• @Julian Get at least one thing done.
• @jdesrosiers Have more collaboration sessions to avoid unclosed topics.
• @gregsdennis Increase diversity in the TSC.
• @Relequestual Discuss as a team about the linting tooling.

Status of JSON Schema Ecosystem

The main discussion of the 1st day started with the Team discussing the current state of the project and its Ecosystem to create a good context for the following discussion to build the roadmap and the vision.

Highlights:

• Hard for new people to contribute. We are not a first time contributor friendly org.
• Most of the tooling is outside our organization and having more tooling in the org could help to get more first time contributors.
• We are focusing on charter/governance being completed.
• For the roadmap, we should communicate how people can contribute to each item.
• We should communicate the status of each objective on our roadmap.
• We could think about what objectives provide the best return on investment.
• We need to think in the project sustainability:
  • More contributors.
  • More companies.
  • More tooling.
  • Community growth.
  • Sponsorships.

Roadmap and Vision

The main objective of the Team summit was to building a 12 months / 5 years roadmap for the project, and to complement the insights captured in the previous Ecosystem discussion we spent time discussing the biggest problems of the project.

What are the biggest problems?

(These numbers don’t imply any specific priority)

Code	Problem	Effort/Impact
1	Lack of governance model	Low effort / Medium impact
2.a	To publish MVP page - Persona direction	Low effort / Mid-high impact
2.b	Fuller documentation for contributing to other projects (such as outside of the org) - for implementers	High effort / Mid-high impact
3.a	Increase JSON Schema visibility inside Postman. This point has been removed from the roadmap because it is internal and affects only to some core members working in that company.
3.b	Financial dependance. Dependency on Postman (for sponsorship/finance FTEs). We could have someone evaluate our financial situation and perspectives	Low-medium effort / Low-medium impact (Does reduce risk)
4.a	Implementations not updating support for newer versions of JSON Schema. Strategy for engaging implementers	Medium effort / High impact
5	Lack of cohesive public face / communication of our status and progress	Low effort / medium impact
6	We don't know if all languages have high quality implementation	Medium/High effort / Medium/High impact
7	Identify a list of interfaces which implementations should have - As an example, being able to load in schemas into a registry, validating references at schema compile time, compiling schema, schema validation without use. Interfaces are different across implementations - Most implementations don't have interfaces to provide users with all of the value they should expect JSON Schema.	Low effort / High impact
8	Spec doesn't allow us to make changes in a compatible way - High effort/high risk to upgrade schemas	High effort / High impact
9	OpenJS Onboarding incomplete	Medium effort / medium-high impact
10	Documentation is not as good as it could be - Using JSON Schema	High effort / Medium-High impact

Planning and prioritization

With the problems identified in the previous discussion we did an impact/effort assessment for solving or fixing each problem, discussing possible solutions. Everyone had an opportunity to pitch on where they felt each item would be on the axis. We debated and adjusted based on consensus.

Roadmap

Based on the prioritization matrix and the previous discussions, we built this 12 months roadmap highlighting the focus for the next 12 months:

The 12 month road map - a proposal
(This list does not imply any specific priority)

• Identify a list of critical interfaces that implementations should have to empower implementers with better resources.
  • Ecosystem | Code: 7 | Prioritization matrix: Low effort / High impact
• Refine the Contributor journey.
  • User Experience | Code: 2.b | Prioritization matrix: High effort / Mid-high impact
• Define a strategy for engaging implementers.
  • Ecosystem | Code: 4.a | Prioritization matrix: Medium effort / High impact
• Complete the new version of the Spec.
  • Specification | Code: 8 | Prioritization matrix: High effort / High impact
• Publish the new webpage.
  • User Experience | Code: 2.a | Prioritization matrix: Low effort / Mid-high impact
• Complete the OpenJS onboarding.
  • Ops | Code: 9 | Prioritization matrix: Medium effort / medium-high impact
• Research of existing implementations by language.
  • Ecosystem | Code: 6 | Prioritization matrix: Low effort / High impact
• Project sustainability strategy.
  • Ops | Code: 3.b | Prioritization matrix: Low-medium effort / Low-medium impact

We probably don't have time to do the following within 12 months

• JSON Schema docs strategy.
  • User Experience | Code: 10 | Prioritization matrix: High effort / Medium-High impact
• Implement and scale the new governance model.
  • Ops | Code: 1 | Prioritization matrix: Low effort / Medium impact
• Enhance public communications strategy.
  • Comms | Code: 5 | Prioritization matrix: Low effort / medium impact

JSON Schema Vision

With the roadmap discussion completed we had another great team discussion with everyone sharing their Vision of JSON Schema, meaning that everything they hope to achieve in the future.

@Julian

• Be a simple and pervasive, easily extensible, cross-language data validation language with a strong core dialect of validation keywords
• Have a wide ecosystem of tools supporting defining data models in JSON with language-specific libraries for building native types (classes)
• Be a positive influence and facilitator of OpenAPI, AsyncAPI and other or other future specifications which build higher level API specifications using JSON Schema functionality

@gregsdennis

• We exist to provide the premier language- and platform-agnostic syntax for validation and annotation of JSON data that is both easy to learn and fully featured.
• Integration into the API call life cycle and other usage arenas

@benjagm

• JSON Schema is recognized by the industry as an ecosystem compound by its tooling + specification generating mutual benefits for both parties.
• JSON Schema offers different engagement programs like OSS Mentoring and JSON Schema Ambassadors.
• JSON Schema is a sustainable project with a strong and diverse TSC and multiple working groups working in different aspects of the Ecosystem.
• JSON Schema provides top notch developer experience to both schema developers and implementers.

@jdesrosiers

• Everyone except legacy projects are off "draft" versions
• Implementations exist for linting schemas and linting JSON based on a schema and are easily integrated into editors and IDEs
• A new version of Hyper-Schema is available and there are implementations in many languages
• Our documentation is easy to use and find information

@Relequestual

• JSON Schema is stable and ready for production
• People can use JSON Schema without surprises
• It's easy to get started with JSON Schema
• Code generation and UI generation tooling for JSON Schema is consistent and reliable
• Non-technical individuals understand the value of JSON Schema
• JSON Schema is the standard of choice for single source of truth data definitions

Idea:
-Action Item: Expand the Implementations page with the ideas of relevant tooling.

Vision themes:

Based in all the individual comments we identified the main themes or working areas for JSON Schema Vision:

• Ecosystem creation and maintenance
  • Special interest groups (e.g. code gen)
  • Mentoring & Ambassadors
  • Relationships (e.g. OpenAPI / AsyncAPI / Hyper-Schema)
• User experience
  • Documentation
  • Consistency / interoperability
• Tooling & implementer support
  • Linters
  • Integration
• Reputation/Trust
  • Trust
  • Credibility
  • Comparison
  • Stability

Identify skills gaps

Based on the roadmap we Identified roles we need (FTE / contract / "bug" bounty / open source)

• Technical writer
• Devops - Automation
• Bug (Issue) triaging
• Bizdev - Business development - Finding more investors / sponsors
• Project management
• Developer

Discuss critical path and requirements for onboarding specific tooling into the organization

The goal of this discussion was to determine if/how we can onboard a limited set of ecosystem critical tooling and the potential implications and what bounds or limits should we consider.

Highlights:

• Who is going to maintain those projects joining the organization? The same person who owns the project.

• If the maintainer leaves the project:

  • One option is to archive it.
  • Another option is looking for support & sponsorship to find someone to maintain it.
  • Find someone in the Community.

• Let’s agree first on the criteria to add a project:

  • TSC Unanimity.
  • Quality.
  • Already has an owner.
  • The project should be coherent with the existing roadmap/vision.

• We won't proactively ask projects to join, instead this procedure is for a very small number of cases.

• Decision: What better fits with our ecosystem is to define a program to engage with implementers, offering resources and support and allowing them to keep the property. For JSON Schema to be successful we need implementers to be successful.

Linting Tooling

Linting is a hot topic in other Ecosystems and we know it can have a potential huge benefit to the wider community so we decided to spend some time discussing a roadmap to releasing a set of linting rules for JSON Schema.

Highlights:

• Spectral is suboptimal for some JSON Schema use cases.
• Action: Let’s identify those cases not supported. Greg Dennis
• We can potentially get features added to Spectral. AsyncAPI already did it.
  • Option A: A language Server might be a great solution. It can have extensibility for different specifications.
  • Option B: ES-Lint as an alternative will use plugins on top and is already a top tier project of the OpenJS foundation. How it handles OpenAPI.
• Spectral’s VS Studio plugin configuration isn’t flexible.
• This is not essential in the short term.

Linting alternatives to Spectral:

• https://github.com/jacksmith15/jsonschema-lint
• https://www.json-schema-linter.com/
• https://github.com/nickcmaynard/jsonschemalint
• ESLint - https://eslint.org/

Project Retrospective

To close the summit we organized a 30 minutes Worked / Not Worked retrospective using ideaboardz.com. The results of the retrospective are available online here.

Not Worked	Votes
Major initiatives like spec release lack direction and high-level planning.	4
long, drawn out discussions that are often abandoned	3
Applications for GSoC and GSoD were not accepted.	2
going to openjs presentation for information (this week)	2
Sometimes I think we dont have clear priorities/ ownership and success metrics	2
voting on a card	1
PRs don’t always have issues. We don’t have PR templates (I think)	1
Development of charter and TSC and governance has been too slow	1
still a lot of implementations that don't support 2020-12	1
We don’t follow up on actions from older meetings	0
Issue templates are not used or not understood.	0

Worked	Votes
collaboration and healthy discussion (this week)	2
significant new funding source	2
Greater community feedback (surveys, hacker news, etc)	2
shared direction and goals (general, with specifics to work out)	2
lots of new people in slack	2
Talented team with huge expertise	2
going to openjs presentation to show presence (this week)	1
weekly meetings is a good cadence	1
Site refresh near done	1
new blogs showing activity for the project	1
joining openjs	1
decent number of new implementations	1
more implementations supporting 2020-12	1
A prospective new JSON Schema book	1
We follow up on actions from the previous meeting	0
submitted applications to GSoC and GSoD (shows activity and interest)	0
some important discussions are resolved	0
More formal research into JSON Schema	0

Contributing

The team just started in-person different discussions as the first step, however we hope other collaborators and Community members will engage the discussion here.

Please add your thoughts and comments on the following topics:

• What is the status of the JSON Schema Ecosystem?
• What are the biggest problems of the project?
• Which should be the Roadmap priorities?
• The JSON Schema Vision.
• How/why Incorporate projects and support implementers?
• How/why develop linting tooling.
• What are the current skills gaps?
• What did not work and what worked in the project.

Next steps

In the next weeks we need everyones feedback and reach consensus before consider any project agreement, but as soon as we have it, we'll build a Github Project with the roadmap breakdown so everyone can explore and contribute.

Finally, we'll love to create a public version of the roadmap to publish it in our website because we know this will help users, contributors and enterprise to better understand the project direction.

Thanks you everyone! ❤️

[benjagm]

Past May 29th we discussed this issue in the OCWM and the group suggested to add the linting ruleset to the roadmap.

[gregsdennis]

I think it's important for us to identify the rules we want separately from any given tool. Translating those into tools can be done as needed for each tool.

This way, we don't limit ourselves to only rules that can be expressed by a given tool.

[benjagm]

it's important for us to identify the rules we want separately from any given tool

I can't agree more. The rules itself will be a great resource for other tool implementers, something really valuable for our Ecosystem.

[Relequestual]

I've created a GitHub Project for a proposed roadmap based on the above 12 month roadmap proposal.
https://github.com/orgs/json-schema-org/projects/14/views/1
I am adding details to the individual tasks based on notes from the in person summit.