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