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.

{ "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" } } }

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 and all major web browsers on Windows, Mac, and Linux

$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:

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

Install using npm:

npm install json-schema-ref-parser

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

const $RefParser = require("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:

import $RefParser from "json-schema-ref-parser";

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.

Full API documentation is available right here

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

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 build script
   npm run build

4. Run the tests
   npm test

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

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