Identify a list of critical interfaces that implementations should have and empower implementers with better resources

[Relequestual]

The ecosystem has many implementations across many languages, but it's often a real challenge to advise people how to do some things the core team would consider fairly basic, for all implemenations.

The specification tells you what must be true about the JSON Schema, and it lays out requirements for what implementations must support, but it doesn't tell implementers how to support specific elements.

One basic example, being able to reference other schemas is something that's required. Some implementations provide an interface to add schemas ahead of time, while others provide a hook function to allow for resolving references at run time.

One way we can help fix this problem is to identify a list of critical interfaces that implementations should have, and empower implementers with better resources.

• Create an initial list based on functionality depended on by Bowtie
  • Known initial examples (to be modified):
    • Draft selection
    • Automatic draft selection based on $schema
    • "Registering" of schemas for referenceability
    • Validation of schemas themselves beyond the metaschema
  • Additional Items to Include (primarily optional specification behavior):
    • Enabling format support
    • Output format support
    • Annotation support
• Decide on serviceable terminology for referencing each piece of functionality
• Add the list of common interfaces with some short prose documentation to a new (non-normative) page on the new website #498
• Ensure implementers of new implementations have some way of recognizing they may want to update the interfaces page with information on their implementation when submitting it for inclusion on the implementations page (PR merged: Add an automatic commenter for new tooling PRs. website#173)

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

[Relequestual]

While this wouldn't be a deliverable for this Issue, it would be awesome if we could encourage implementations to also create and encode their supported interfaces, and link to related docs for each interface. This would be dependent on other work not yet done, but recording it for future us.

[gregsdennis]

Just looking at the options my lib supports, these might make this list (in addition to some of the above):

1. Vocabulary registration (includes custom keyword definitions) - This seems fairly critical to supporting 2020-12.
2. Logging (e.g. validation walk-through) - My implementation can product logging output as it navigates the schema(s) and evaluates each keyword. Good for debugging. Not mentioned in the spec, though, so ??? (Edit: as of v5, my implementation no longer supports logging. New architecture doesn't allow it in the same way.)
3. Automatic resolution and fetching of references - Should be disabled by default, but mine (and my guess is a lot of others) can support this.
4. Specifying/Selecting output format

@jdesrosiers also does some pre-processing (compiling) in his lib. I wonder how many others do something like this. (Edit: as of v5, mine now does this.) (Probably worth a separate issue, but it might be nice to explore the analysis that's he's doing and document, if not standardize, some of it as a pattern to follow.)

[Julian]

(The list I put in the description was super barebones, I did less than 30 seconds of thinking -- with a task itself to go collect said interfaces -- all that being said, keep listing em! Definitely useful.)

[gregsdennis]

For this work, are we expecting to perform a survey of implementations to document (or link to docs) how they implement these interfaces?

[Julian]

I assume by "how they implement" you mean more "what function do I call" rather than "what is their internals" -- in which case yes I think so in the sense that we can then possibly generalize into "look for something like X" -- but I don't think we can/should necessarily list for every implementation what the precise API is, that's quite hard for the same reason as:

link to docs

(I don't think this will work well though personally -- interlinking in certain languages is easy, but definitely not all, let alone lots of languages all at once. I think actually linking to docs will be a recipe for broken links and/or lots of maintenance to keep the page working)