All $RefParser
methods accept an optional options
parameter, which you can use to customize how the JSON Schema is parsed, resolved, dereferenced, etc.
If you pass an options parameter, you don't need to specify every option. Any options you don't specify will use their default values.
$RefParser.dereference("my-schema.yaml", {
parse: {
json: false, // Disable the JSON parser
yaml: {
allowEmpty: false // Don't allow empty YAML files
},
text: {
canParse: [".txt", ".html"], // Parse .txt and .html files as plain text (strings)
encoding: 'utf16' // Use UTF-16 encoding
}
},
resolve: {
file: false, // Don't resolve local file references
http: {
timeout: 2000, // 2 second timeout
withCredentials: true, // Include auth credentials when resolving HTTP references
}
},
dereference: {
circular: false // Don't allow circular $refs
}
});
The parse
options determine how different types of files will be parsed.
JSON Schema $Ref Parser comes with built-in JSON, YAML, plain-text, and binary parsers, any of which you can configure or disable. You can also add your own custom parsers if you want.
Option(s) | Type | Description |
---|---|---|
json yaml text binary |
object boolean |
These are the built-in parsers. In addition, you can add your own custom parsers To disable a parser, just set it to false . |
json.order yaml.order text.order binary.order |
number |
Parsers run in a specific order, relative to other parsers. For example, a parser with order: 5 will run before a parser with order: 10 . If a parser is unable to successfully parse a file, then the next parser is tried, until one succeeds or they all fail.You can change the order in which parsers run, which is useful if you know that most of your referenced files will be a certain type, or if you add your own custom parser that you want to run first. |
json.allowEmpty yaml.allowEmpty text.allowEmpty binary.allowEmpty |
boolean |
All of the built-in parsers allow empty files by default. The JSON and YAML parsers will parse empty files as undefined . The text parser will parse empty files as an empty string. The binary parser will parse empty files as an empty byte array.You can set allowEmpty: false on any parser, which will cause an error to be thrown if a file empty. |
json.canParse yaml.canParse text.canParse binary.canParse |
boolean , RegExp , string , array , function |
Determines which parsers will be used for which files. A regular expression can be used to match files by their full path. A string (or array of strings) can be used to match files by their file extension. Or a function can be used to perform more complex matching logic. See the custom parser docs for details. |
text.encoding |
string |
The encoding to use when parsing text-based files. The default is "utf8". |
The resolve
options control how JSON Schema $Ref Parser will resolve file paths and URLs, and how those files will be read/downloaded.
JSON Schema $Ref Parser comes with built-in support for HTTP and HTTPS, as well as support for local files (when running in Node.js). You can configure or disable either of these built-in resolvers. You can also add your own custom resolvers if you want.
Option(s) | Type | Description |
---|---|---|
external |
boolean |
Determines whether external $ref pointers will be resolved. If this option is disabled, then external $ref pointers will simply be ignored. |
file http |
object boolean |
These are the built-in resolvers. In addition, you can add your own custom resolvers To disable a resolver, just set it to false . |
file.order http.order |
number |
Resolvers run in a specific order, relative to other resolvers. For example, a resolver with order: 5 will run before a resolver with order: 10 . If a resolver is unable to successfully resolve a path, then the next resolver is tried, until one succeeds or they all fail.You can change the order in which resolvers run, which is useful if you know that most of your file references will be a certain type, or if you add your own custom resolver that you want to run first. |
file.canRead http.canRead |
boolean , RegExp , string , array , function |
Determines which resolvers will be used for which files. A regular expression can be used to match files by their full path. A string (or array of strings) can be used to match files by their file extension. Or a function can be used to perform more complex matching logic. See the custom resolver docs for details. |
http.headers |
object |
You can specify any HTTP headers that should be sent when downloading files. For example, some servers may require you to set the Accept or Referrer header. |
http.timeout |
number |
The amount of time (in milliseconds) to wait for a response from the server when downloading files. The default is 5 seconds. |
http.redirects |
number |
The maximum number of HTTP redirects to follow per file. The default is 5. To disable automatic following of redirects, set this to zero. |
http.withCredentials |
boolean |
Set this to true if you're downloading files from a CORS-enabled server that requires authentication |
The dereference
options control how JSON Schema $Ref Parser will dereference $ref
pointers within the JSON schema.
Option(s) | Type | Description |
---|---|---|
circular |
boolean or "ignore" |
Determines whether circular $ref pointers are handled.If set to false , then a ReferenceError will be thrown if the schema contains any circular references.If set to "ignore" , then circular references will simply be ignored. No error will be thrown, but the $Refs.circular property will still be set to true . |