json-schema-ref-parser

What is json-schema-ref-parser?

The json-schema-ref-parser npm package is a tool that can parse JSON Schema files and dereference $ref pointers. This allows you to combine multiple separate JSON Schema files into one resolved schema, validate JSON documents against schemas, and manipulate JSON Schemas programmatically.

What are json-schema-ref-parser's main functionalities?

Dereferencing $ref pointers

This feature allows you to take a JSON Schema that contains $ref pointers to other files or URLs and resolve them into a single JSON Schema object. This is useful for simplifying and flattening schemas that are spread across multiple files.

{"$ref": "http://example.com/my-schema.json"}

Bundle schemas into a single file

This feature lets you take a JSON Schema with $ref pointers to other files in your project and bundle them all into a single JSON Schema file. This can be useful for distribution or for loading a schema from a single file in a browser or other environments where multiple files are not convenient.

{"$ref": "definitions.json#/address"}

Parse JSON Schema to a JavaScript object

This feature allows you to parse a JSON Schema from a string, file, or URL into a JavaScript object. This can be useful for manipulating the schema programmatically or for using it in conjunction with other tools that operate on JavaScript objects.

{"type": "object", "properties": {"name": {"type": "string"}}}

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.

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:

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

2. Install dependencies
   npm install

3. Run the build script
   npm run build

4. 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.