Package Exports

json-schema-ref-parser
json-schema-ref-parser/dist/ref-parser
json-schema-ref-parser/lib/dereference
json-schema-ref-parser/lib/options
json-schema-ref-parser/lib/promise
json-schema-ref-parser/lib/refs
json-schema-ref-parser/lib/util

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (json-schema-ref-parser) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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": {
            "$ref": "schemas/people/Bruce-Wayne.json"
        },
        "place": {
            "$ref": "schemas/places.yaml#/definitions/Gotham-City"
        },
        "thing": {
            "$ref": "http://wayne-enterprises.com/things/batmobile"
        },
        "color": {
            "$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.

Features

Works in Node, io.js, and all major web browsers on Windows, Mac, and Linux
Supports JSON and YAML formats — even a mix of both!
Resolves all $ref pointers, including pointers to external files and URLs
Configurable caching of external files
Supports circular references, nested references, back-references, and cross-references between files
Can dereference your schema, combining everything into a single JavaScript object that's easy to work with
Different $ref pointers to the same value resolve to the same object instance, thus maintaining reference equality
You can choose to dereference only internal $refs, external $refs, or both

Installation

Install using npm or bower, or just download ref-parser.js or ref-parser.min.js.

Node

npm install json-schema-ref-parser

Bower

bower install json-schema-ref-parser

Sample Usage

// 
// 
// 
// !!! Coming Soon !!!
//
// NOTE: This project is still in alpha.  The API and syntax may change before release
// 
// 
// 
//

Circular $Refs

JSON Schema files can contain circular $ref pointers, and JSON Schema $Ref Parser will detect them and handle them correctly. Circular $ref pointers will be resolved and dereferenced just like any other $ref pointer. However, this means that the resulting dereferenced JavaScript object will contain circular object references. This isn't a problem if you just plan to use the object programmatically, but if you attempt to serialize a circular object to JSON, you will receive an error. Just be aware of that.

"person": {
    "properties": {
        "name": {
          "type": "string"
        },
        "spouse": {
          "type": {
            "$ref": "#/person"        // circular reference
          }
        }
    }
}

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)

License

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