1 | JSON Schema $Ref Parser
|
2 | ============================
|
3 | #### Parse, Resolve, and Dereference JSON Schema $ref pointers
|
4 |
|
5 | [![Build Status](https://api.travis-ci.org/BigstickCarpet/json-schema-ref-parser.svg?branch=master)](https://travis-ci.org/BigstickCarpet/json-schema-ref-parser)
|
6 | [![Dependencies](https://david-dm.org/BigstickCarpet/json-schema-ref-parser.svg)](https://david-dm.org/BigstickCarpet/json-schema-ref-parser)
|
7 | [![Coverage Status](https://coveralls.io/repos/BigstickCarpet/json-schema-ref-parser/badge.svg?branch=master&service=github)](https://coveralls.io/r/BigstickCarpet/json-schema-ref-parser)
|
8 | [![Codacy Score](https://api.codacy.com/project/badge/d8abfe5e9a4044b89bd9f4b999d4a574)](https://www.codacy.com/public/jamesmessinger/json-schema-ref-parser)
|
9 | [![Inline docs](http://inch-ci.org/github/BigstickCarpet/json-schema-ref-parser.svg?branch=master&style=shields)](http://inch-ci.org/github/BigstickCarpet/json-schema-ref-parser)
|
10 |
|
11 | [![npm](http://img.shields.io/npm/v/json-schema-ref-parser.svg)](https://www.npmjs.com/package/json-schema-ref-parser)
|
12 | [![Bower](http://img.shields.io/bower/v/json-schema-ref-parser.svg)](http://bower.io/)
|
13 | [![License](https://img.shields.io/npm/l/json-schema-ref-parser.svg)](LICENSE)
|
14 |
|
15 | [![Browser Compatibility](https://saucelabs.com/browser-matrix/json-schema-parser.svg)](https://saucelabs.com/u/json-schema-parser)
|
16 |
|
17 |
|
18 | The Problem:
|
19 | --------------------------
|
20 | 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.
|
21 |
|
22 | ```javascript
|
23 | {
|
24 | "definitions": {
|
25 | "person": {
|
26 | // references an external file
|
27 | "$ref": "schemas/people/Bruce-Wayne.json"
|
28 | },
|
29 | "place": {
|
30 | // references a sub-schema in an external file
|
31 | "$ref": "schemas/places.yaml#/definitions/Gotham-City"
|
32 | },
|
33 | "thing": {
|
34 | // references a URL
|
35 | "$ref": "http://wayne-enterprises.com/things/batmobile"
|
36 | },
|
37 | "color": {
|
38 | // references a value in an external file via an internal reference
|
39 | "$ref": "#/definitions/thing/properties/colors/black-as-the-night"
|
40 | }
|
41 | }
|
42 | }
|
43 | ```
|
44 |
|
45 |
|
46 | The Solution:
|
47 | --------------------------
|
48 | JSON Schema $Ref Parser is a full [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and [JSON Pointer](https://tools.ietf.org/html/rfc6901) implementation that crawls even the most complex [JSON Schemas](http://json-schema.org/latest/json-schema-core.html) and gives you simple, straightforward JavaScript objects.
|
49 |
|
50 | - Use **JSON** or **YAML** schemas — or even a mix of both!
|
51 | - Supports `$ref` pointers to external files and URLs, as well as [custom sources](docs/plugins/resolvers.md) such as databases
|
52 | - Can [bundle](docs/ref-parser.md#bundlepath-options-callback) multiple files into a single schema that only has _internal_ `$ref` pointers
|
53 | - Can [dereference](docs/ref-parser.md#dereferencepath-options-callback) your schema, producing a plain-old JavaScript object that's easy to work with
|
54 | - Supports [circular references](docs/README.md#circular-refs), nested references, back-references, and cross-references between files
|
55 | - Maintains object reference equality — `$ref` pointers to the same value always resolve to the same object instance
|
56 | - [Tested](http://bigstickcarpet.github.io/json-schema-ref-parser/test/index.html) in Node, io.js, and all major web browsers on Windows, Mac, and Linux
|
57 |
|
58 |
|
59 | Example
|
60 | --------------------------
|
61 |
|
62 | ```javascript
|
63 | $RefParser.dereference(mySchema, function(err, schema) {
|
64 | if (err) {
|
65 | console.error(err);
|
66 | }
|
67 | else {
|
68 | // `schema` is just a normal JavaScript object that contains your entire JSON Schema,
|
69 | // including referenced files, combined into a single object
|
70 | console.log(schema.definitions.person.properties.firstName);
|
71 | }
|
72 | });
|
73 | ```
|
74 |
|
75 | Or use [Promises syntax](http://javascriptplayground.com/blog/2015/02/promises/) instead. The following example is the same as above:
|
76 |
|
77 | ```javascript
|
78 | $RefParser.dereference(mySchema)
|
79 | .then(function(schema) {
|
80 | console.log(schema.definitions.person.properties.firstName);
|
81 | })
|
82 | .catch(function(err) {
|
83 | console.error(err);
|
84 | });
|
85 | ```
|
86 |
|
87 | For more detailed examples, please see the [API Documentation](docs/README.md)
|
88 |
|
89 |
|
90 | Installation
|
91 | --------------------------
|
92 | #### Node
|
93 | Install using [npm](https://docs.npmjs.com/getting-started/what-is-npm):
|
94 |
|
95 | ```bash
|
96 | npm install json-schema-ref-parser
|
97 | ```
|
98 |
|
99 | Then require it in your code:
|
100 |
|
101 | ```javascript
|
102 | var $RefParser = require('json-schema-ref-parser');
|
103 | ```
|
104 |
|
105 | #### Web Browsers
|
106 | Install using [bower](http://bower.io/):
|
107 |
|
108 | ```bash
|
109 | bower install json-schema-ref-parser
|
110 | ```
|
111 |
|
112 | Then reference [`ref-parser.js`](dist/ref-parser.js) or [`ref-parser.min.js`](dist/ref-parser.min.js) in your HTML:
|
113 |
|
114 | ```html
|
115 | <script src="bower_components/json-schema-ref-parser/dist/ref-parser.js"></script>
|
116 | ```
|
117 |
|
118 | Or, if you're using AMD (Require.js), then import it into your module:
|
119 |
|
120 | ```javascript
|
121 | define(["ref-parser"], function($RefParser) { /* your module's code */ })
|
122 | ```
|
123 |
|
124 |
|
125 | API Documentation
|
126 | --------------------------
|
127 | Full API documentation is available [right here](docs/README.md)
|
128 |
|
129 |
|
130 | Contributing
|
131 | --------------------------
|
132 | I welcome any contributions, enhancements, and bug-fixes. [File an issue](https://github.com/BigstickCarpet/json-schema-ref-parser/issues) on GitHub and [submit a pull request](https://github.com/BigstickCarpet/json-schema-ref-parser/pulls).
|
133 |
|
134 | #### Building/Testing
|
135 | To build/test the project locally on your computer:
|
136 |
|
137 | 1. __Clone this repo__<br>
|
138 | `git clone https://github.com/bigstickcarpet/json-schema-ref-parser.git`
|
139 |
|
140 | 2. __Install dependencies__<br>
|
141 | `npm install`
|
142 |
|
143 | 3. __Run the build script__<br>
|
144 | `npm run build`
|
145 |
|
146 | 4. __Run the unit tests__<br>
|
147 | `npm run mocha` (test in Node)<br>
|
148 | `npm run karma` (test in web browsers)<br>
|
149 | `npm test` (test in Node and browsers, and report code coverage)
|
150 |
|
151 | 5. __Start the local web server__<br>
|
152 | `npm start` (then browse to [http://localhost:8080/test/index.html](http://bigstickcarpet.com/json-schema-ref-parser/test/index.html))
|
153 |
|
154 |
|
155 | License
|
156 | --------------------------
|
157 | JSON Schema $Ref Parser is 100% free and open-source, under the [MIT license](LICENSE). Use it however you want.
|