Remove external ref resolving

[sdirix]

Overview

Refs (i.e. $ref) are a core part of the JSON Schema specification. At the moment JSON Forms tackles it with different concepts.

• UI Schema scopes (which are defined as JSON pointers) are manually resolved against the JSON Schema
• When the resolving ends in a $ref, JSON Forms manually resolves the $ref

But JSON Forms also supports ref-resolving via json-schema-ref-parser. As a concept it is implemented in @jsonforms/core, however only the React renderers are actually using it.

The implemented functionality is:

• The React Dispatch renderer checks whether there are any $refs in its schema. This is checked via copied code from json-refs which adds the dependencies uri-js and uuid to @jsonforms-core.
• If there are any, the json-schema-ref-parser is tasked with resolving all of them. The json-schema-ref-parser can be configured via options which allows configuring resolving even to external paths, e.g. https://whatever.com/example.json. The resulting JSON Schema is then actually used.

Problems

• The check for $refs in the dispatch renderer is relatively slow.
• json-schema-ref-parser is really slow, and especially so for circular JSON Schemas. Also it's run unconditionally in React, even when the integrated manually resolving would be enough.
• We have three additional dependencies for this in the @jsonforms/core although only one binding is actually using it.
• The dependencies of json-schema-ref-parser are actually Node dependencies which can't be run in the Browser. Any application using JSON Forms therefore also needs to add polyfills to actually run it. Up until Webpack 4 this happened automatically. With Webpack 5 this was removed, leading to build errors when using JSON Forms. It doesn't make a good impression when using JSON Forms requires Node polyfills.

Overall there is hardly any benefit to all of this. Yes, we allow resolving external refs, however as the actual resolving method has to be handed in anyway AND it is run unconditionally in most cases, the respective developer could just resolve them beforehand and then hand them in to JSON Forms. This is actually what we recommend for example for the Angular renderers and demonstrate in the Angular seed.

Downsides of removing ref resolving

Potential downsides when removing this without replacement:

• There could be cases where the implemented manually resolving was aided by json-schema-ref-parser, i.e. handed in JSON Schemas were prepared in a way which allowed the manually resolving to actually work. This worry is mitigated a bit by the Angular renderers as they never used this resolving. Still the React renderers support more complicated schemas, e.g. oneOf etc.
• Some users requested this feature, so they will certainly rely on it. Their setups will break and they'll need to resolve their schemas before handing them over to JSON Forms.

Mitigation idea

To still allow external refs to be resolved in general, we could offer a resolving customization method. If the user hands in such a function, it will be called whenever something needs to be resolved. The user can then implement arbitrary behavior here, including resolving to external paths.

Tl;dr

The current external ref resolving approach using json-schema-ref-parser has too many downsides to keep it like it is in the current form. Removing it will break some users, but they should be mostly fine by resolving the schemas themselves before handing it to JSON Forms. We can offer a customization method which would allow for all previously supported use cases (and many more) but this requires work by the user.

[sdirix]

Additional requirements for a release

Adapt migration guide

Add a small motivation why we performed this change, with a link to this issue.
Mention that there is no difference for Angular and Vue users.
Most React users should also not be affected.
Problematic cases are mostly complex $ref setups, often in combination with anyOf, allOf, oneOf.
The old behavior can be restored by resolving the references before handing the schema over to JSON Forms.
Add an example how to resolve the schema with json-schema-ref-parser and one with json-refs.

Website

We should introduce versioning in our Website for the 3.0 release.
Move current content to an (unlinked) ref-resolving-legacy page and add an info box on the new ref-resolving.
Explain in the ref-resolving section that JSON Forms only supports basic ref resolving out of the box and that complex cases might fail.
Showcase a complex example, you can use anyOf-oneOf-allOf-resolve as a basis.
However if that is a use case, it can be supported by resolving the schema before handing it over to JSON Forms.
Explain in same or more detail as in the migration guide how schemas can be resolved before handing them over to JSON Forms.

[sdirix]

PR #1762 removes json-schema-ref-parser from JSON Forms. However to fully close this issue we need to look into the crashing examples and make the resolving code more robust.

[sdirix]

Completed with #1829