Complete the new version of the Spec

[benjagm]

Problem: The scope the of next specification release is distributed among different issues and PRs. Some of the items have been included in milestones but not all what makes it difficult to progress with the release discussions. By identifying the pending scope and applying some project management to support the progress we hope to lighten the whole process.

Team working on this issue:

• @benjagm to project manage this work.
• @jdesrosiers and @gregdennis to write up list of work the believe still needs to be done.

Assessed as high impact/high effort during our collaborators summit 2023.

Updated plan:

• We'll create a new milestone called stable-release. We'll create a project board to enhance collaboration and transparency.
  Milestone: https://github.com/json-schema-org/json-schema-spec/milestone/10
  Project Board: Stable Release Development (view)
• We'll conduct a grooming session to setup the initial spec backlog associating the issues with the new milestone.
• We'll decide if we remove the existing milestones.
• We'll decide a labelling system to identify the issues' workflow. Before, during and after an issue is added to the spec scope.
• We'll run 1 week cycles to decide the issues to focus on during that cycle. 1 session at the beginning to decide scope of the cycle and 1 session at the end to review the closed issues, and decide the issues for the next cycle. Short cycles can be done in during the OCWM.

[gregsdennis]

I plan on bringing this up in the call next week, there are a lot of open questions that need answering before we can consider starting actual work on the spec again.

• We have to align on our definition of compatibility: https://github.com/orgs/json-schema-org/discussions/404
• I think with the last call we decided we'll do a stable URI + release URIs for meta-schemas. ✔️
• We need to restart the SDLC discussions.
• We need to decide whether we'll assign URIs to keywords: URI naming scheme for user/one-off/non-standard keywords json-schema-spec#1401 & Add keyword id to output unit json-schema-spec#1065
• Are we extracting output from the core spec? Extract output to a separate specification json-schema-spec#1320 & Gregsdennis/output spec json-schema-spec#1385
• We need to decide on how we're going to edit the document. Convert the spec to Markdown json-schema-spec#1335, Convert the spec to Markdown json-schema-spec#1357, & Convert to Markdown json-schema-spec#1412

And those are just from the collection of tabs I keep open in my browser. There are definitely more in the issues and discussions lists. One of these should probably be a prune/clean of those lists.

[gregsdennis]

Ideally, I'd like this to be more than just a couple of guys writing the spec. I'd like to get wider input, but that input only seems to come when we post specific issues in public forums. Even then, the comments we do get are generally loosely tangential rather than helpful.

[jdesrosiers]

Here's a list of things I had in mind before things went off the rails, https://github.com/json-schema-org/json-schema-spec/issues?q=is%3Aissue+is%3Aopen+label%3Asdlc

These are the main issues I think need we need to resolve before we can really dive into spec changes.

• How are new features added and evolved (and possibly removed)?
  1. Staged stability process
  2. External extension specifications
  3. Add, deprecate, remove
• What features will be included in the first release?
  1. 2020-12
  2. 2020-12 + new keywords
  3. Some subset of 2020-12
  4. draft-07
  5. 2020-12 limited to what is compatible with draft-07

Here's a lightly ogranized and incomplete survey of discussions, issues, PRs, and ADRs related to the next release.

• IETF Decoupling
  • Convert the spec to Markdown json-schema-spec#1357
  • Convert to Markdown json-schema-spec#1412
• Foundations
  • What kind of changes will be allowed and when
    • https://github.com/orgs/json-schema-org/discussions/404
    • https://github.com/orgs/json-schema-org/discussions/282
    • https://github.com/orgs/json-schema-org/discussions/234
    • Add PROCESS.md documenting the new SDLC json-schema-spec#1348
    • https://github.com/json-schema-org/json-schema-spec/blob/main/adr/2022-11-stable-spec.md
  • Supporting forward compatibility
    • Unknown keywords
      • https://github.com/orgs/json-schema-org/discussions/241
      • https://github.com/orgs/json-schema-org/discussions/329
      • Specify a naming scheme for non-assertion keywords json-schema-spec#1399
  • https://github.com/orgs/json-schema-org/discussions/204
• Keywords
  • RequireAllExcept - Add requireAllExcept keyword json-schema-spec#1144
  • DynamicRef
    • Remove initial resolution - Drop the initial resolve step for dynamic references json-schema-spec#1142
    • Remove bookending - Remove bookending requirement for dynamicRef json-schema-spec#1139
• Dialects
  • Should there be a default dialect? https://github.com/orgs/json-schema-org/discussions/405
  • Require explicit dialect
    • https://github.com/orgs/json-schema-org/discussions/190
    • Put boundaries on lack of "$schema" behavior json-schema-spec#1353
• Vocabularies
  • Remove optional vocabularies? https://github.com/orgs/json-schema-org/discussions/342
• Media Type
  • IANA registration https://github.com/orgs/json-schema-org/discussions/198
  • Should we decouple JSON Schema the language (not format specific) from JSON Schema the media-type (coupled to JSON)?

json-schema-org/json-schema-spec#1420
json-schema-org/json-schema-spec#1421

[gregsdennis]

I think we should probably do a complete "compatibility" survey of the text describing each feature. @jdesrosiers brought up a good point regarding JSON pointers that cross schema resource boundaries being defined but not required. Things like this could come back to haunt us.