JSON Schema $Ref Parser

_This package needs a new maintainer or at least some contributors. For more information please read this article. As of v10.0.0 I am no longer spending any time working on this tool, so I can focus on scaling up my reforestation charity instead of burning myself out trying to maintain a whole load of OSS projects I don't use in my vanishingly small spare time. Get in touch if you'd like to take over. - Phil Sturgeon_

#### Parse, Resolve, and Dereference JSON Schema $ref pointers



The Problem:
--------------------------
You've got a JSON Schema with $ref pointers to other files and/or URLs. Maybe you know all the referenced files ahead of time. Maybe you don't. Maybe some are local files, and others are remote URLs. Maybe they are a mix of JSON and YAML format. Maybe some of the files contain cross-references to each other.

``javascript
{
"definitions": {
"person": {
// references an external file
"$ref": "schemas/people/Bruce-Wayne.json"
},
"place": {
// references a sub-schema in an external file
"$ref": "schemas/places.yaml#/definitions/Gotham-City"
},
"thing": {
// references a URL
"$ref": "http://wayne-enterprises.com/things/batmobile"
},
"color": {
// references a value in an external file via an internal reference
"$ref": "#/definitions/thing/properties/colors/black-as-the-night"
}
}
}
`


The Solution:
--------------------------
JSON Schema $Ref Parser is a full JSON Reference and JSON Pointer implementation that crawls even the most complex JSON Schemas and gives you simple, straightforward JavaScript objects.

- Use JSON or YAML schemas — or even a mix of both!
- Supports $ref pointers to external files and URLs, as well as custom sources such as databases
- Can bundle multiple files into a single schema that only has _internal_ $ref pointers
- Can dereference your schema, producing a plain-old JavaScript object that's easy to work with
- Supports circular references, nested references, back-references, and cross-references between files
- Maintains object reference equality — $ref pointers to the same value always resolve to the same object instance
- Tested in Node v10, v12, & v14, and all major web browsers on Windows, Mac, and Linux


Example
--------------------------

`javascript
$RefParser.dereference(mySchema, (err, schema) => {
if (err) {
console.error(err);
}
else {
// schema is just a normal JavaScript object that contains your entire JSON Schema,
// including referenced files, combined into a single object
console.log(schema.definitions.person.properties.firstName);
}
})
`

Or use async/await syntax instead. The following example is the same as above:

`javascript
try {
let schema = await $RefParser.dereference(mySchema);
console.log(schema.definitions.person.properties.firstName);
}
catch(err) {
console.error(err);
}
`

For more detailed examples, please see the API Documentation

Installation
--------------------------
Install using npm:

`bash
npm install @apidevtools/json-schema-ref-parser
`

Usage
--------------------------
When using JSON Schema $Ref Parser in Node.js apps, you'll probably want to use CommonJS syntax:

`javascript
const $RefParser = require("@apidevtools/json-schema-ref-parser");
`

When using a transpiler such as Babel or TypeScript, or a bundler such as Webpack or Rollup, you can use ECMAScript modules syntax instead:

`javascript
import $RefParser from "@apidevtools/json-schema-ref-parser";
`

If you are using Node.js < 18, you'll need a polyfill for fetch, like node-fetch:
`javascript
import fetch from "node-fetch";

globalThis.fetch = fetch;
`

Browser support
--------------------------
JSON Schema $Ref Parser supports recent versions of every major web browser. Older browsers may require Babel and/or polyfills.

To use JSON Schema $Ref Parser in a browser, you'll need to use a bundling tool such as Webpack, Rollup, Parcel, or Browserify. Some bundlers may require a bit of configuration, such as setting browser: true in rollup-plugin-resolve.

API Documentation
--------------------------
Full API documentation is available right here

Contributing
--------------------------
I welcome any contributions, enhancements, and bug-fixes. Open an issue on GitHub and submit a pull request.

#### Building/Testing
To build/test the project locally on your computer:

1. __Clone this repo__

git clone https://github.com/APIDevTools/json-schema-ref-parser.git

2. __Install dependencies__

npm install

3. __Run the tests__

npm test`

License
--------------------------
JSON Schema $Ref Parser is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To
--------------------------
Thanks to these awesome companies for their support of Open Source developers ❤