TypeScript icon, indicating that this package has built-in type declarations

1.2.0 • Public • Published

JSON Schema $Ref Parser

Parse, Resolve, and Dereference JSON Schema $ref pointers

Build Status npm License

OS and Browser Compatibility

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.

  "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


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

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

try {
  const schema = await $RefParser.dereference(mySchema);
} catch(err) {

For more detailed examples, please see the API Documentation


Install using npm:

npm install @readme/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("@readme/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 "@readme/json-schema-ref-parser";

Differences from @apidevtools/json-schema-ref-parser

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


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.

Package Sidebar


npm i @readme/json-schema-ref-parser

Weekly Downloads






Unpacked Size

138 kB

Total Files


Last publish


  • gratcliff
  • dannobytes
  • gkoberger
  • domharrington
  • mjcuva
  • kanadgupta
  • jonursenbach
  • rafegoldberg
  • dashron
  • iliast