What's coming in v2.0

[jdesrosiers]

The following are most of my ideas for the next version of @hyperjump/json-schema. The primary goal for this release is to make the changes needed to support schema linting. The actual linting feature can come after release. The goal is to get to a place where it can be added without having to introduce any further breaking changes. Since I'm introducing a new major version I also want to take the opportunity to make some other important changes that would require breaking changes.

Unified

V1 uses ASTs to represent both schemas and instances. The goal for v2 is to convert those ASTs to use the unist specification for syntax trees. This change allows us to take advantage of the unified ecosystem. The primary reason for adopting unified is to be able to use their existing utilities for implementing linting. A secondary benefit is that we can make use of the unified CLI to include a CLI for performing validation from the CLI. This can be used for things like creating a Github Action for validating and linting all the schemas in a codebase.

Schema model improvements

In v1, the schema AST is little more than a JSON AST. It's necessary to add more information to this representation in order to support linting. We need to know if a node represents a schema, a keyword, or just a plain JSON value. If it's a schema, we need to know what dialect it is. If it's a keyword we need to know it's keyword URI. Due to some some of the rules about referencing and what is considered as schema, this is actually quite complicated to get right.

Schema traversal plugins

I recently introduced the concept of EvaluationPlugins. This has proven to be very useful, but has some limitations. EvaluationPlugins follow the execution of the validation process, which means it requires a JSON instance. However, some things you might want to do with a schema doesn't include an instance. For example, linting a schema needs to traverse the schema without the context of a JSON instance. For v2 I'd like to introduce something like EvaluationPlugins for schema traversal. I don't have a clear vision for what that will look like yet, but I expect this is how linting will be implemented.

Multiple validator instances

In v1, the validator is a singleton. There can be only one configuration and set of schemas per process. The goal for v2 is to encapsulate everything into a self contained instance. This allows for multiple instances to be used without conflicting with each other. This is especially necessary if writing a library that uses this project. The schemas and configuration used by the library should be isolated from the schemas and configuration used by the application using the library.

Type safety

V1 includes types for the public API, but not internally. The goal for v2 is to enable type checking for the whole project. TypeScript syntax is still out of the question due to the required build step, but TypeScript's integration with JavaScript/JSDoc is good enough now to make this step. Part of this upgrade will be to include JSDoc documentation for the public API so people get documentation in their editor.

[jdesrosiers]

Here's what I've done so far ...

Everything is build on top of @hyperjump/browser, which is what's used handle references. So that's where I started. I've already built v2 including a unist compliant AST for JSON, unified integrations, unified CLI, type safety, and a class called Hyperjump for encapsulation. I think the basics are pretty stable at this point, but there are still details to work out.

The idea is that there will be a JsonSchema class that extends Hyperjump adding additional methods like validate and introducing a unist AST for JSON Schema. My vision is to load dialects and extra features with mixins. I've done enough of a proof of concept to be convinced that this is possible and can be done in a type safe way, but I'm not 100% convinced it's the best approach. Anyway, it would look something like this,

const jsonSchema = new JsonSchema(generalConfig)
  .with(draft07) // Loads support for draft-07
  .with(draft202012) // Loads support for 2020-12
  .with(BundlePlugin, bundlerConfig) // Adds the "bundle" method
  .with(AnnotationsPlugin, annotationsConfig); // Adds the "annotate" method

jsonSchema.validate(schemaUri, instance);
jsonSchema.bundle(schemaUri);
jsonSchema.annotate(schemaUri, instance);

I think I have most of the unist compliant schema AST and parser figured out including the schema model improvements that are needed for the linting feature. With any luck, it should be relatively easy to port the v1 implementation over to the new design once that's done.

What are the blockers?

I don't think I have any at the moment, but there are a lot of unknowns. The main thing holding me up is that I don't have time to work on it right now.

How can I help?

Unfortunately, most of the details and context for the problems that need to be solved exist only in my head right now. I'll try to start documenting those things later, but I've already spent more time than I have on this write up, so it will have to wait for now.