Skip to main content

Ref Resolving legacy


With version 3.0 of JSON Forms, we no longer include json-schema-ref-parser within the core package. For a migration guide, have a look here.

The following information is legacy documentation only relevant for the React renderers in JSON Forms < 3.0

Sometimes it might not be possible to have just a single schema that you can pass to JSON Forms or it might make sense to split up a very big schema into multiple smaller ones for maintenance reasons.

If that's the case, you can add a custom ref resolver based on JSON Schema \$Ref parser that determines how $refs will be resolved. You'll also need to adapt the AJV validator in order to enable validation of the referenced schema.

To do so, use the refParserOptions and ajv props of the JsonForms component and pass in the ref resolver together with the AJV instance.

Here's an example of how to accomplish this. We'll first create a customized AJV instance. yourSchemaObject is the actual schema to be referenced while yourSchemaIdentifier is the id that can be used to reference the schema via a $ref.

const ajv = createAjv();
ajv.addSchema(yourSchemaObject, 'yourSchemaIdentifier');

Next, we'll set up the ref resolver. The implementation is up to you, but you'll need to implement a canRead method that determines whether a current ref needs to be resolved and a read method that returns the actual schema. The order property determines the order in which resolvers are executed, until the first one returns true for canRead. For more info about ref resolving please see the JSON Schema \$Ref parser documentation. Note that the name for the actual resolver, which we called foo here, does not actually matter.

const yourSchemaResolver = {
order: 1,
canRead: function(file) {
return file.url.indexOf('yourSchemaIdentifier') !== -1;
read: function() {
return JSON.stringify(yourSchemaObject);
const refParserOptions = {
resolve: {
foo: yourSchemaResolver,

Finally, you'll need to pass your resolver and ajv instance to JSON Forms:


With these changes refs like $ref: yourSchemaIdentifier#something will be resolved accordingly.