json-schema-ref-parser

JSON Schema $Ref Parser

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.

{
  "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!
• Fully supports $ref pointers to external files and URLs
• Configurable caching of referenced files
• 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, io.js, and all major web browsers on Windows, Mac, and Linux

Example

$RefParser.dereference(mySchema, function(err, schema) {
  if (err) {
    console.error(err);
  }
  else {
    // `schema` is just a normal JavaScript object that contains your
    // entire JSON Schema - even if it spans multiple files
    console.log(schema.definitions.person.properties.firstName);
  }
});

Or use Promises syntax instead. The following example is the same as above:

$RefParser.dereference(mySchema)
  .then(function(schema) {
    console.log(schema.definitions.person.properties.firstName);
  })
  .catch(function(err) {
    console.error(err);
  });

For more detailed examples, please see the API Documentation

Installation

Node

Install using npm:

npm install json-schema-ref-parser

Then require it in your code:

var $RefParser = require('json-schema-ref-parser');

Web Browsers

Install using bower:

bower install json-schema-ref-parser

Then reference ref-parser.js or ref-parser.min.js in your HTML:

<script src="bower_components/json-schema-ref-parser/dist/ref-parser.js"></script>

Or, if you're using AMD (Require.js), then import it into your module:

define(["ref-parser"], function($RefParser) { /* your module's code */ })

API Documentation

Full API documentation is available right here

Contributing

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

Building/Testing

To build/test the project locally on your computer:

• Clone this repo
  git clone https://github.com/bigstickcarpet/json-schema-ref-parser.git

• Install dependencies
  npm install

• Run the build script
  npm run build

• Run the unit tests
  npm run mocha (test in Node)
  npm run karma (test in web browsers)
  npm test (test in Node and browsers, and report code coverage)

• Start the local web server
  npm start (then browse to http://localhost:8080/tests/index.html)

License

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

Similar packages

Other packages similar to json-schema-ref-parser

ajv

Ajv is a JSON Schema validator that allows you to compile and validate JSON Schemas. It is similar to json-schema-ref-parser in that it can handle $ref pointers, but its primary focus is on validation rather than parsing and dereferencing.

json-schema

The json-schema package is another tool for validating JSON data against JSON Schemas. It is similar to json-schema-ref-parser in that it can parse and validate schemas, but it does not have the same focus on resolving $ref pointers.

tv4

Tiny Validator (tv4) is a small and fast JSON Schema validator. It is similar to json-schema-ref-parser in that it can validate JSON documents against schemas, but it does not provide the same level of support for dereferencing and bundling schemas.