JSON Schema $Ref Parser

Parse, Resolve, and Dereference JSON Schema $ref pointers

Installation

Install using npm:

1npm install @apidevtools/json-schema-ref-parser
2yarn add @apidevtools/json-schema-ref-parser
3bun add @apidevtools/json-schema-ref-parser

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.

1{
2  "definitions": {
3    "person": {
4      // references an external file
5      "$ref": "schemas/people/Bruce-Wayne.json"
6    },
7    "place": {
8      // references a sub-schema in an external file
9      "$ref": "schemas/places.yaml#/definitions/Gotham-City"
10    },
11    "thing": {
12      // references a URL
13      "$ref": "http://wayne-enterprises.com/things/batmobile"
14    },
15    "color": {
16      // references a value in an external file via an internal reference
17      "$ref": "#/definitions/thing/properties/colors/black-as-the-night"
18    }
19  }
20}

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
• Compatible with Node LTS and beyond, and all major web browsers on Windows, Mac, and Linux

Example

1import $RefParser from "@apidevtools/json-schema-ref-parser";
2
3try {
4  await $RefParser.dereference(mySchema);
5  // note - by default, mySchema is modified in place, and the returned value is a reference to the same object
6  console.log(mySchema.definitions.person.properties.firstName);
7
8  // if you want to avoid modifying the original schema, you can disable the `mutateInputSchema` option
9  let clonedSchema = await $RefParser.dereference(mySchema, { mutateInputSchema: false });
10  console.log(clonedSchema.definitions.person.properties.firstName);
11} catch (err) {
12  console.error(err);
13}

For more detailed examples, please see the API Documentation

Polyfills

If you are using Node.js < 18, you'll need a polyfill for fetch, like node-fetch:

1import fetch from "node-fetch";
2
3globalThis.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.

Webpack 5

Webpack 5 has dropped the default export of node core modules in favour of polyfills, you'll need to set them up yourself ( after npm-installing them ) Edit your webpack.config.js :

1config.resolve.fallback = {
2  path: require.resolve("path-browserify"),
3  fs: require.resolve("browserify-fs"),
4};
5
6config.plugins.push(
7  new webpack.ProvidePlugin({
8    Buffer: ["buffer", "Buffer"],
9  }),
10);

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
   yarn install

3. Run the tests
   yarn test

License

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

Thanks

Thanks to these awesome contributors for their major support of this open-source project.

• JonLuca De Caro
• Phil Sturgeon
• Stoplight