JSON Schema $Ref Parser API

Things to Know

• Class methods vs. Instance methods
• Callbacks vs. Promises
• Circular references

Classes & Methods

The$RefParser class

• schema property
• $refs property
• dereference() method
• bundle() method
• parse() method
• resolve() method

The$Refs class

• circular property
• paths() method
• values() method
• exists() method
• get() method
• set() method

TheOptions object

Class methods vs. Instance methods

All of JSON Schema $Ref Parser’s methods are available as static (class) methods, and as instance methods. The static methods simply create a new$RefParser instance and then call the corresponding instance method. Thus, the following line…

$RefParser.bundle("my-schema.json");

… is the same as this:

letparser=new$RefParser();parser.bundle("my-schema.json");

The difference is that in the second example you now have a reference toparser, which means you can access the results (parser.schema andparser.$refs) anytime you want, rather than just in the callback function.

Callbacks vs. Promises

Many people preferPromise syntax orasync/await instead of callbacks. JSON Schema $Ref Parser allows you to use whichever one you prefer.

If you pass a callback function to any method, then the method will call the callback using the Node.js error-first convention. If you donot pass a callback function, then the method will return a Promise.

The following two examples are equivalent:

// Callback syntax$RefParser.dereference(mySchema,(err,api)=>{if(err){// Error}else{// Success}});

try{// async/await syntaxletapi=await$RefParser.dereference(mySchema);// Success}catch(err){// Error}

Circular $Refs

JSON Schema files can containcircular $ref pointers, and JSON Schema $Ref Parser fully supports them. Circular references can be resolved and dereferenced just like any other reference. However, if you intend to serialize the dereferenced schema as JSON, then you should be aware thatJSON.stringify does not support circular references by default, so you will need touse a custom replacer function.

You can disable circular references by setting thedereference.circular option tofalse. Then, if a circular reference is found, aReferenceError will be thrown.

Or you can choose to just ignore circular references altogether by setting thedereference.circular option to"ignore". In this case, all non-circular references will still be dereferenced as normal, but any circular references will remain in the schema.

Another option is to use thebundle method rather than thedereference method. Bundling doesnot result in circular references, because it simply convertsexternal$ref pointers tointernal ones.

"person":{"properties":{"name":{"type":"string"},"spouse":{"type":{"$ref":"#/person"// circular reference}}}}