Moved the API docs out of the root ReadMe file and into a "docs" folder

Author: JamesMessinger

.npmignore

@@ -5,6 +5,7 @@ npm-debug.log
 /.idea
 /coverage
 /dist/*.test.js
+/docs
 karma.conf.js
 /tests
 /www

README.md

@@ -17,6 +17,7 @@
   },
   "ignore": [
     "/bower_components",
+    "/docs",
     "/lib",
     "/www",
     "/dist/*.test.js",

bower.json

@@ -0,0 +1,78 @@
+JSON Schema $Ref Parser API
+==========================
+
+### [`$RefParser`](ref-parser.md)
+- [`schema`](ref-parser.md#schema)
+- [`$refs`](ref-parser.md#refs)
+- [`dereference()`](ref-parser.md#dereferencepath-options-callback)
+- [`bundle()`](ref-parser.md#bundlepath-options-callback)
+- [`parse()`](ref-parser.md#parsepath-options-callback)
+- [`resolve()`](ref-parser.md#resolvepath-options-callback)
+
+### [`$Refs`](refs.md)
+- [`circular`](refs.md#circular)
+- [`paths()`](refs.md#pathstypes)
+- [`values()`](refs.md#valuestypes)
+- [`isExpired()`](refs.md#isexpiredref)
+- [`expire()`](refs.md#expireref)
+- [`exists()`](refs.md#existsref)
+- [`get()`](refs.md#getref-options)
+- [`set()`](refs.md#setref-value-options)
+
+### [`YAML`](yaml.md)
+- [`parse()`](yaml.md#parsetext)
+- [`stringify()`](yaml.md#stringifyvalue)
+
+### [`Options`](options.md)
+
+
+Topics
+---------------------
+- [Class methods vs. Instance methods](#class-methods-vs-instance-methods)
+- [Callbacks vs. Promises](#callbacks-vs-promises)
+- [Circular references](#circular-refs)
+
+
+### Class methods vs. Instance methods
+All of JSON Schema $Ref Parser's methods are available as static (class) methods, and as instance methods.  The static methods simply create a new [`$RefParser`](ref-parser.md) instance and then call the corresponding instance method.  Thus, the following line...
+
+```javascript
+$RefParser.resolve("my-schema.json");
+```
+
+... is the same as this:
+
+```javascript
+var parser = new $RefParser();
+parser.resolve("my-schema.json");
+```
+
+The difference is that in the second example you now have a reference to `parser`, which means you can access the results ([`parser.schema`](ref-parser.md#schema) and [`parser.$refs`](ref-parser.md#refs)) anytime you want, rather than just in the callback function. Also, having a `$RefParser` instance allows you to benefit from **[caching](options.md#caching)**, so the next time you call [`parser.resolve()`](ref-parser.md#resolveschema-options-callback), it won't need to re-download those files again (as long as the cache hasn't expired).
+
+
+### Callbacks vs. Promises
+Many people prefer [ES6 Promise syntax](http://javascriptplayground.com/blog/2015/02/promises/) instead of callbacks.  JSON Schema $Ref Parser allows you to use whichever one you prefer.  Every method accepts an optional callback _and_ returns a Promise.  So pick your poison.
+
+
+Circular $Refs
+--------------------------
+JSON Schema files can contain [circular $ref pointers](https://gist.github.com/BigstickCarpet/d18278935fc73e3a0ee1), and JSON Schema $Ref Parser fully supports them. Circular references can be resolved and dereferenced just like any other reference.  However, if you intend to serialize the dereferenced schema as JSON, then you should be aware that [`JSON.stringify`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) does not support circular references by default, so you will need to [use a custom replacer function](https://stackoverflow.com/questions/11616630/json-stringify-avoid-typeerror-converting-circular-structure-to-json).
+
+You can disable circular references by setting the [`$refs.circular`](options.md) option to `false`. Then, if a circular reference is found, a `ReferenceError` will be thrown.
+
+Another option is to use the [`bundle`](ref-parser.md#bundleschema-options-callback) method rather than the [`dereference`](ref-parser.md#dereferenceschema-options-callback) method.  Bundling does _not_ result in circular references, because it simply converts _external_ `$ref` pointers to _internal_ ones.
+
+```javascript
+"person": {
+    "properties": {
+        "name": {
+          "type": "string"
+        },
+        "spouse": {
+          "type": {
+            "$ref": "#/person"        // circular reference
+          }
+        }
+    }
+}
+```

docs/README.md

@@ -0,0 +1,35 @@
+Options
+==========================
+
+All [`$RefParser`](ref-parser.md) methods accept an optional `options` parameter, which you can use to customize how the JSON Schema is parsed, resolved, dereferenced, etc.
+
+If you pass an options parameter, you _don't_ need to specify _every_ option.  Any options you don't specify will use their default values, as shown below.
+
+```javascript
+$RefParser.dereference("my-schema.yaml", {
+    allow: {
+        json: false,        // Don't allow JSON files
+        empty: false        // Don't allow empty files
+    },
+    $refs: {
+        internal: false     // Don't dereference internal $refs, only external
+    },
+    cache: {
+        fs: 1,              // Cache local files for 1 second
+        http: 600           // Cache http URLs for 10 minutes
+    }
+});
+```
+
+|Option           |Type     |Default   |Description
+|:----------------|:--------|:---------|:----------
+|`allow.json`     |bool     |true      |Determines whether JSON files are supported
+|`allow.yaml`     |bool     |true      |Determines whether YAML files are supported<br> (note: all JSON files are also valid YAML files)
+|`allow.empty`    |bool     |true      |Determines whether it's ok for a `$ref` pointer to point to an empty file
+|`allow.unknown`  |bool     |true      |Determines whether it's ok for a `$ref` pointer to point to an unknown/unsupported file type (such as HTML, text, image, etc.). The default is to resolve unknown files as a [`Buffer`](https://nodejs.org/api/buffer.html#buffer_class_buffer)
+|`$refs.internal` |bool     |true      |Determines whether internal `$ref` pointers (such as `#/definitions/widget`) will be dereferenced when calling [`dereference()`](ref-parser.md#dereferenceschema-options-callback).  Either way, you'll still be able to get the value using [`$Refs.get()`](refs.md#getref-options)
+|`$refs.external` |bool     |true      |Determines whether external `$ref` pointers get resolved/dereferenced. If `false`, then no files/URLs will be retrieved.  Use this if you only want to allow single-file schemas.
+|`$refs.circular` |bool     |true      |Determines whether [circular `$ref` pointers](README.md#circular-refs) are allowed. If `false`, then a `ReferenceError` will be thrown if the schema contains a circular reference.
+|`cache.fs`       |number   |60        |<a name="caching"></a>The length of time (in seconds) to cache local files.  The default is one minute.  Setting to zero will cache forever.
+|`cache.http`     |number   |300       |The length of time (in seconds) to cache HTTP URLs.  The default is five minutes.  Setting to zero will cache forever.
+|`cache.https`    |number   |300       |The length of time (in seconds) to cache HTTPS URLs.  The default is five minutes.  Setting to zero will cache forever.

docs/options.md

@@ -0,0 +1,167 @@
+`$RefParser` class
+==========================
+
+This is the default export of JSON Schema $Ref Parser.  You can creates instances of this class using `new $RefParser()`, or you can just call its [static methods](README.md#class-methods-vs-instance-methods).
+
+##### Properties
+- [`schema`](#schema)
+- [`$refs`](#refs)
+
+##### Methods
+- [`dereference()`](#dereferencepath-options-callback)
+- [`bundle()`](#bundlepath-options-callback)
+- [`parse()`](#parsepath-options-callback)
+- [`resolve()`](#resolvepath-options-callback)
+
+
+### `Schema`
+The `schema` property is the parsed/bundled/dereferenced JSON Schema object.  This is the same value that is passed to the callback function (or Promise) when calling the [`parse`](#parseschema-options-callback), [`bundle`](#bundleschema-options-callback), or [`dereference`](#dereferenceschema-options-callback) methods.
+
+```javascript
+var parser = new $RefParser();
+
+parser.schema;                  // => null
+
+parser.dereference("my-schema.json")
+  .then(function(schema) {
+    typeof parser.schema;       // => "object"
+
+    schema === parser.schema;   // => true
+  });
+```
+
+
+### `$refs`
+The `$refs` property is a [`$Refs`](refs.md) object, which lets you access all of the externally-referenced files in the schema, as well as easily get and set specific values in the schema using JSON pointers.
+
+This is the same value that is passed to the callback function (or Promise) when calling the [`resolve`](#resolveschema-options-callback) method.
+
+```javascript
+var parser = new $RefParser();
+
+parser.$refs.paths();           // => [] empty array
+
+parser.dereference("my-schema.json")
+  .then(function() {
+    parser.$refs.paths();       // => ["my-schema.json"]
+  });
+```
+
+
+
+### `dereference(schema, [options], [callback])`
+
+- **schema** (_required_) - `string` or `object`<br>
+A JSON Schema object, or the file path or URL of a JSON Schema file.  See the [`parse`](#parseschema-options-callback) method for more info.
+
+- **options** (_optional_) - `object`<br>
+See [options](options.md) for the full list of options
+
+- **callback** (_optional_) - `function(err, schema)`<br>
+A callback that will receive the dereferenced schema object
+
+- **Return Value:** `Promise`<br>
+See [Callbacks vs. Promises](README.md#callbacks-vs-promises)
+
+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.
+
+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](README.md#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.
+
+```javascript
+$RefParser.dereference("my-schema.yaml")
+  .then(function(schema) {
+    // The `schema` object is a normal JavaScript object,
+    // so you can easily access any part of the schema using simple dot notation
+    console.log(schema.definitions.person.properties.firstName); // => {type: "string"}
+
+    // Object reference equality works as expected
+    schema.definitions.thing === schema.definitions.batmobile;   // => true
+  });
+```
+
+
+### `bundle(schema, [options], [callback])`
+
+- **schema** (_required_) - `string` or `object`<br>
+A JSON Schema object, or the file path or URL of a JSON Schema file.  See the [`parse`](#parseschema-options-callback) method for more info.
+
+- **options** (_optional_) - `object`<br>
+See [options](options.md) for the full list of options
+
+- **callback** (_optional_) - `function(err, schema)`<br>
+A callback that will receive the bundled schema object
+
+- **Return Value:** `Promise`<br>
+See [Callbacks vs. Promises](README.md#callbacks-vs-promises)
+
+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).
+
+This also eliminates the risk of [circular references](README.md#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).
+
+```javascript
+$RefParser.bundle("my-schema.yaml")
+  .then(function(schema) {
+    console.log(schema.definitions.person); // => {$ref: "#/definitions/schemas~1people~1Bruce-Wayne.json"}
+  });
+```
+
+
+### `parse(schema, [options], [callback])`
+
+- **schema** (_required_) - `string` or `object`<br>
+A JSON Schema object, or the file path or URL of a JSON Schema file.
+<br><br>
+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.
+
+- **options** (_optional_) - `object`<br>
+See [options](options.md) for the full list of options
+
+- **callback** (_optional_) - `function(err, schema)`<br>
+A callback that will receive the parsed schema object, or an error
+
+- **Return Value:** `Promise`<br>
+See [Callbacks vs. Promises](README.md#callbacks-vs-promises)
+
+> 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.
+
+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.
+
+```javascript
+$RefParser.parse("my-schema.yaml")
+  .then(function(schema) {
+    console.log(schema.definitions.person); // => {$ref: "schemas/people/Bruce-Wayne.json"}
+  });
+```
+
+
+### `resolve(schema, [options], [callback])`
+
+- **path** (_required_) - `string` or `object`<br>
+A JSON Schema object, or the file path or URL of a JSON Schema file.  See the [`parse`](#parseschema-options-callback) method for more info.
+
+- **options** (_optional_) - `object`<br>
+See [options](options.md) for the full list of options
+
+- **callback** (_optional_) - `function(err, $refs)`<br>
+A callback that will receive a [`$Refs`](refs.md) object
+
+- **Return Value:** `Promise`<br>
+See [Callbacks vs. Promises](README.md#callbacks-vs-promises)
+
+> This method is used internally by other methods, such as [`bundle`](#bundleschema-options-callback) and [`dereference`](#dereferenceschema-options-callback).  You probably won't need to call this method yourself.
+
+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.md) object, which is a map of all the resolved references and their values.
+
+```javascript
+$RefParser.resolve("my-schema.yaml")
+  .then(function($refs) {
+    // $refs.paths() returns the paths of all the files in your schema
+    var filePaths = $refs.paths();
+
+    // $refs.get() lets you query parts of your schema
+    var name = $refs.get("schemas/people/Bruce-Wayne.json#/properties/name");
+
+    // $refs.set() lets you change parts of your schema
+    $refs.set("schemas/people/Bruce-Wayne.json#/properties/favoriteColor/default", "black");
+  });
+```