JSON Schema at scale in organizations

[miqui]

@benjagm - Hi, this disc. is a followup to topic about using JSON schema at scale (i.e across organizations). I think the idea was that, eventually, we would gather enough community experiences to generate some guidance type of documentation.

[miqui]

My 2 cents:
My last org: approx 1.5k people of which several hundred were developers, DevOps, Cloud engineers and architects.

• 1st problem was to educate the organization where to get educated (and get help) for the JSON spec.
  • Content side of the problem was mostly solved by the current spec site.
  • Getting to the information is an internal organizational issue (and here is where the scale problem manifests itself)
• 2nd Which draft to use?
• 3rd Once a draft was debated ad nauseam, then naturally, different groups within the org never wanted to change the draft version.
• 4th Not all groups in an organization selected the same draft. Governance ended up being "do what works for you"
• 5th Compatablity issues with OpenAPI 3.x and JSON Schema. (But this has gotten better with 3.1)
• 6th Tooling choices were fragmented which made 2nd problem harder.

[gregsdennis]

You've seen the discussion where we're trying to define a way to bring some stability into spec development (you commented there). That effort is aimed to alleviate a few of these, like deciding which draft to use. With compatible releases, you shouldn't have to make that decision (at least not very often).

Some of the others, like guidance docs, are something we're working through with the recent website changes. We know that our docs are... lacking. We're working on it, but the Understanding JSON Schema is the most thorough thing we have right now.

Additionally, there are some things, like schema registries, where we really can't make recommendations because different orgs have different requirements. Recently, I think we've landed on the idea of creating some lists of strategies we've seen to serve as a starting point, but we wouldn't directly endorse any of them.

[miqui]

You've seen the discussion where we're trying to define a way to bring some stability into spec development (you commented there). That effort is aimed to alleviate a few of these, like deciding which draft to use. With compatible releases, you shouldn't have to make that decision (at least not very often).

Agreed. The friction of the decision should be reduced gradually, if not altogether.

Some of the others, like guidance docs, are something we're working through with the recent website changes. We know that our docs are... lacking. We're working on it, but the Understanding JSON Schema is the most thorough thing we have right now.

Yes on the Understanding of JSON Schema, but is this guidance that you mention not aimed at the problems I described earlier?

Additionally, there are some things, like schema registries, where we really can't make recommendations because different orgs have different requirements. Recently, I think we've landed on the idea of creating some lists of strategies we've seen to serve as a starting point, but we wouldn't directly endorse any of them.

ok, I'll find the background on these strategies that serve as a starting point. This is most def interesting.

Thanks for your feedback.

[gregsdennis]

(@miqui please move this into the appropriate thread. The discussions UI isn't great and this is a common mistake. I'll address your concerns in the thread once you've moved it.)