Skip to main content

Ref Resolving


Ref resolving is only supported out of the box within the React renderers.

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 eample 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.