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:
let parser = new $RefParser();
parser.bundle("my-schema.json");
The difference is that in the second example you now have a reference to parser
, which means you can access the results (parser.schema
and parser.$refs
) anytime you want, rather than just in the callback function.
Many people prefer Promise syntax or async
/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 do not 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 syntax
let api = await $RefParser.dereference(mySchema);
// Success
}
catch (err) {
// Error
}
JSON Schema files can contain circular $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 that JSON.stringify
does not support circular references by default, so you will need to use a custom replacer function.
You can disable circular references by setting the dereference.circular
option to false
. Then, if a circular reference is found, a ReferenceError
will be thrown.
Or you can choose to just ignore circular references altogether by setting the dereference.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 the bundle
method rather than the dereference
method. Bundling does not result in circular references, because it simply converts external $ref
pointers to internal ones.
"person": {
"properties": {
"name": {
"type": "string"
},
"spouse": {
"type": {
"$ref": "#/person" // circular reference
}
}
}
}