JSON Schema Explainer (And AST)

[Relequestual]

Summary

Much like regular expression, JSON Schema has features that are easy to understand, and some which require looking up references or using tools to understand. Regular expression has tools like https://regex101.com which provides a way to easily understand and digest what the regular expression is doing and what each part of the regex actually means. JSON Schema has no such tool.

A solution should be two fold:

• Create an Abstract Syntax Tree (AST) of any given JSON Schema
• Use the AST to create an interactive web based application which can explain different parts of a schema.

Even something as simple as identifying which objects are subschemas and which are not will help.

Project Duration: 175 hours (Maybe? Finding it hard to judge)

Use Case

An AST from JSON Schema that can be used by a front end to explain what a JSON Schema does, also has the ability to be used by other applications to build in such utility. A web base interactive UI to process the resutling AST is not only useful to schema authors and debuggers, but also proves evidence that the AST provides enough value.

Knowledge Required

Javascript, node, NPM/Yarn, React/Vue, AST, JSON Schema (preferable).

[jviotti]

Great proposal @Relequestual ! I'm super excited to see something like this come to life.

Create an Abstract Syntax Tree (AST) of any given JSON Schema

As a side thought, we should design the AST in a way that also forms the basis for advanced JSON Schema syntax highlighting. What do you think?

Use the AST to create an interactive web based application which can explain different parts of a schema.

You can even show the JSON Schema and the matching instance side by side and when you hover on i.e. a subschema, you can see specifically which part of the document is taking into account, and even which keywords are being taken into account.

[jviotti]

I think this is one instance of a larger and very interesting problem: creating an expressive AST out of JSON Schema is the core to solve many of the static analysis problems showing up on related tooling:

• Generating documentation out of JSON Schema
• Generating syntax highlighters
• Generating encoding rules from JSON Schema (in the case of JSON BinPack)
• Linting JSON Schemas
• Performing code-generation out of JSON Schema
• Downgrading JSON Schema definitions in order to let applications adopt later versions of JSON Schema while relying on older tooling

And probably more. Most of these tools would re-invent the static analysis wheel in some way or another, so having everything on top a unified AST definition would help a lot.

[jviotti]

I think the key is the push back as much metadata about the schema that i.e. validators typically know when evaluating the schema into the AST. For example, the AST for a specific node can contain things like:

• The place from the input schema where that node is defined
• The place/s in the document that will be evaluated for that schema
• The type of node (i.e. annotation, assertion, reference, etc)
• The vocabulary that defines such node (if any)
• etc

Then, if you i.e. know there a specific contains keyword is in the schema, the path where it must me matched in the instance, the fact that is an assertion, and that it is the contains keyword from the validation vocabulary, then you can easily write rules to explain the meaning in the web-app, highlight the corresponding parts in the schema and the document, etc.

[jviotti]

Framing my specific use case on top of the concept of an AST, I would need to:

• Convert an input JSON Schema into its AST
• Simplify the schema definition at the AST level
• Convert the AST back into a JSON Schema