Skip to content

Commit 244d639

Browse files
JamesMessingerJamesMessinger
committed
- Moved the most commonly-used methods to the top of the documentation.
- Added notes to methods that are mostly for internal use
1 parent 3481040 commit 244d639

1 file changed

Lines changed: 49 additions & 46 deletions

File tree

‎README.md‎

Lines changed: 49 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -124,11 +124,10 @@ define(["ref-parser"], function($RefParser) { /* your module's code */ })
124124
The API
125125
--------------------------
126126
- Methods
127+
- [`dereference()`](#dereferencepath-options-callback)
128+
- [`bundle()`](#bundlepath-options-callback)
127129
- [`parse()`](#parsepath-options-callback)
128130
- [`resolve()`](#resolvepath-options-callback)
129-
- [`bundle()`](#bundlepath-options-callback)
130-
- [`dereference()`](#dereferencepath-options-callback)
131-
- [`validate()`](#validatepath-options-callback)
132131
- Objects
133132
- [`Options`](#options)
134133
- [`Schema`](#schema-object)
@@ -147,116 +146,120 @@ The API
147146
- [Callbacks vs. Promises](#callbacks-vs-promises)
148147

149148

150-
### `parse(path, [options], [callback])`
149+
### `dereference(path, [options], [callback])`
151150

152-
- **path** (_required_) - `string`<br>
153-
The file path or URL of your JSON Schema file. The path can be absolute or relative. In Node, the path is relative to `process.cwd()`. In the browser, it's relative to the URL of the page.
154-
<br><br>
155-
If you already have the JSON Schema as a JavaScript object, then you can pass that instead of a file path.
151+
- **path** (_required_) - `string` or `object`<br>
152+
The file path or URL of your JSON Schema file. See the [`parse`](#parsepath-options-callback) method for more info.
156153

157154
- **options** (_optional_) - `object`<br>
158155
See [options](#options) below.
159156

160157
- **callback** (_optional_) - `function(err, schema)`<br>
161-
A callback that will receive the parsed schema object, or an error.
158+
A callback that will receive the dereferenced schema object.
162159

163160
- **Return Value:** `Promise`<br>
164161
See [Callbacks vs. Promises](#callbacks-vs-promises) below.
165162

166-
Parses the given JSON Schema file (in JSON or YAML format), and returns it as a JavaScript object. This method **does not** resolve `$ref` pointers or dereference anything. It simply parses _one_ file and returns it.
163+
Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain _any_ `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
164+
165+
The `dereference` method maintains object reference equality, meaning that all `$ref` pointers that point to the same object will be replaced with references to the same object. Again, this is great for programmatic usage, but it does introduce the risk of [circular references](#circular-refs), so be careful if you intend to serialize the schema using [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Consider using the [`bundle`](#bundlepath-options-callback) method instead, which does not create circular references.
167166

168167
```javascript
169-
$RefParser.parse("my-schema.yaml")
168+
$RefParser.dereference("my-schema.yaml")
170169
.then(function(schema) {
171-
console.log(schema.definitions.person); // => {$ref: "schemas/people/Bruce-Wayne.json"}
170+
// The `schema` object is a normal JavaScript object,
171+
// so you can easily access any part of the schema using simple dot notation
172+
console.log(schema.definitions.person.properties.firstName); // => {type: "string"}
173+
174+
// Object reference equality works as expected
175+
schema.definitions.thing === schema.definitions.batmobile; // => true
172176
});
173177
```
174178

175179

176-
### `resolve(path, [options], [callback])`
180+
### `bundle(path, [options], [callback])`
177181

178182
- **path** (_required_) - `string` or `object`<br>
179183
The file path or URL of your JSON Schema file. See the [`parse`](#parsepath-options-callback) method for more info.
180184

181185
- **options** (_optional_) - `object`<br>
182186
See [options](#options) below.
183187

184-
- **callback** (_optional_) - `function(err, $refs)`<br>
185-
A callback that will receive a [`$Refs`](#refs-object) object.
188+
- **callback** (_optional_) - `function(err, schema)`<br>
189+
A callback that will receive the bundled schema object.
186190

187191
- **Return Value:** `Promise`<br>
188192
See [Callbacks vs. Promises](#callbacks-vs-promises) below.
189193

190-
Resolves all JSON references (`$ref` pointers) in the given JSON Schema file. If it references any other files/URLs, then they will be downloaded and resolved as well (unless `options.$refs.external` is false). This method **does not** dereference anything. It simply gives you a [`$Refs`](#refs-object) object, which is a map of all the resolved references and their values.
191-
192-
```javascript
193-
$RefParser.resolve("my-schema.yaml")
194-
.then(function($refs) {
195-
// $refs.paths() returns the paths of all the files in your schema
196-
var filePaths = $refs.paths();
194+
Bundles all referenced files/URLs into a single schema that only has _internal_ `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain _internal_ JSON references rather than being [fully-dereferenced](#dereferencepath-options-callback).
197195

198-
// $refs.get() lets you query parts of your schema
199-
var name = $refs.get("schemas/people/Bruce-Wayne.json#/properties/name");
196+
This also eliminates the risk of [circular references](#circular-refs), so the schema can be safely serialized using [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
200197

201-
// $refs.set() lets you change parts of your schema
202-
$refs.set("schemas/people/Bruce-Wayne.json#/properties/favoriteColor/default", "black");
198+
```javascript
199+
$RefParser.bundle("my-schema.yaml")
200+
.then(function(schema) {
201+
console.log(schema.definitions.person); // => {$ref: "#/definitions/schemas~1people~1Bruce-Wayne.json"}
203202
});
204203
```
205204

206205

207-
### `bundle(path, [options], [callback])`
206+
### `parse(path, [options], [callback])`
208207

209-
- **path** (_required_) - `string` or `object`<br>
210-
The file path or URL of your JSON Schema file. See the [`parse`](#parsepath-options-callback) method for more info.
208+
- **path** (_required_) - `string`<br>
209+
The file path or URL of your JSON Schema file. The path can be absolute or relative. In Node, the path is relative to `process.cwd()`. In the browser, it's relative to the URL of the page.
210+
<br><br>
211+
If you already have the JSON Schema as a JavaScript object, then you can pass that instead of a file path.
211212

212213
- **options** (_optional_) - `object`<br>
213214
See [options](#options) below.
214215

215216
- **callback** (_optional_) - `function(err, schema)`<br>
216-
A callback that will receive the bundled schema object.
217+
A callback that will receive the parsed schema object, or an error.
217218

218219
- **Return Value:** `Promise`<br>
219220
See [Callbacks vs. Promises](#callbacks-vs-promises) below.
220221

221-
Bundles all referenced files/URLs into a single schema that only has _internal_ `$ref` pointers. This lets you split-up your schema however you want while you're building it, but easily combine all those files together when it's time to package or distribute the schema to other people. The resulting schema size will be small, since it will still contain _internal_ JSON references rather than being [fully-dereferenced](#dereferencepath-options-callback).
222+
> This method is used internally by other methods, such as [`bundle`](#bundlepath-options-callback) and [`dereference`](#dereferencepath-options-callback). You probably won't need to call this method yourself.
222223
223-
This also eliminates the risk of [circular references](#circular-refs), so the schema can be safely serialized using [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).
224+
Parses the given JSON Schema file (in JSON or YAML format), and returns it as a JavaScript object. This method **does not** resolve `$ref` pointers or dereference anything. It simply parses _one_ file and returns it.
224225

225226
```javascript
226-
$RefParser.bundle("my-schema.yaml")
227+
$RefParser.parse("my-schema.yaml")
227228
.then(function(schema) {
228-
console.log(schema.definitions.person); // => {$ref: "#/definitions/schemas~1people~1Bruce-Wayne.json"}
229+
console.log(schema.definitions.person); // => {$ref: "schemas/people/Bruce-Wayne.json"}
229230
});
230231
```
231232

232233

233-
### `dereference(path, [options], [callback])`
234+
### `resolve(path, [options], [callback])`
234235

235236
- **path** (_required_) - `string` or `object`<br>
236237
The file path or URL of your JSON Schema file. See the [`parse`](#parsepath-options-callback) method for more info.
237238

238239
- **options** (_optional_) - `object`<br>
239240
See [options](#options) below.
240241

241-
- **callback** (_optional_) - `function(err, schema)`<br>
242-
A callback that will receive the dereferenced schema object.
242+
- **callback** (_optional_) - `function(err, $refs)`<br>
243+
A callback that will receive a [`$Refs`](#refs-object) object.
243244

244245
- **Return Value:** `Promise`<br>
245246
See [Callbacks vs. Promises](#callbacks-vs-promises) below.
246247

247-
Dereferences all `$ref` pointers in the JSON Schema, replacing each reference with its resolved value. This results in a schema object that does not contain _any_ `$ref` pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.
248+
> This method is used internally by other methods, such as [`bundle`](#bundlepath-options-callback) and [`dereference`](#dereferencepath-options-callback). You probably won't need to call this method yourself.
248249
249-
The `dereference` method maintains object reference equality, meaning that all `$ref` pointers that point to the same object will be replaced with references to the same object. Again, this is great for programmatic usage, but it does introduce the risk of [circular references](#circular-refs), so be careful if you intend to serialize the schema using [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify). Consider using the [`bundle`](#bundlepath-options-callback) method instead, which does not create circular references.
250+
Resolves all JSON references (`$ref` pointers) in the given JSON Schema file. If it references any other files/URLs, then they will be downloaded and resolved as well (unless `options.$refs.external` is false). This method **does not** dereference anything. It simply gives you a [`$Refs`](#refs-object) object, which is a map of all the resolved references and their values.
250251

251252
```javascript
252-
$RefParser.dereference("my-schema.yaml")
253-
.then(function(schema) {
254-
// The `schema` object is a normal JavaScript object,
255-
// so you can easily access any part of the schema using simple dot notation
256-
console.log(schema.definitions.person.properties.firstName); // => {type: "string"}
253+
$RefParser.resolve("my-schema.yaml")
254+
.then(function($refs) {
255+
// $refs.paths() returns the paths of all the files in your schema
256+
var filePaths = $refs.paths();
257257

258-
// Object reference equality works as expected
259-
schema.definitions.thing === schema.definitions.batmobile; // => true
258+
// $refs.get() lets you query parts of your schema
259+
var name = $refs.get("schemas/people/Bruce-Wayne.json#/properties/name");
260+
261+
// $refs.set() lets you change parts of your schema
262+
$refs.set("schemas/people/Bruce-Wayne.json#/properties/favoriteColor/default", "black");
260263
});
261264
```
262265

0 commit comments

Comments
 (0)