json-schema-deref

Dereference JSON pointers in a JSON schemas with their true resolved values. A lighter synchronous version of this module is available as json-schema-deref-sync, but omits web references and custom loaders.

Installation

npm install json-schema-deref

Overview

Let's say you have the following JSON Schema:

{
  "description": "Just some JSON schema.",
  "title": "Basic Widget",
  "type": "object",
  "definitions": {
    "id": {
      "description": "unique identifier",
      "type": "string",
      "minLength": 1,
      "readOnly": true
    }
  },
  "properties": {
    "id": {
      "$ref": "#/definitions/id"
    },
    "foo": {
      "$ref": "http://www.mysite.com/myschema.json#/definitions/foo"
    },
    "bar": {
      "$ref": "bar.json"
    }
  }
}

Sometimes you just want that schema to be fully expanded, with $ref's being their (true) resolved values:

{
  "description": "Just some JSON schema.",
  "title": "Basic Widget",
  "type": "object",
  "definitions": {
    "id": {
      "description": "unique identifier",
      "type": "string",
      "minLength": 1,
      "readOnly": true
    }
  },
  "properties": {
    "id": {
      "description": "unique identifier",
      "type": "string",
      "minLength": 1,
      "readOnly": true
    },
    "foo": {
      "description": "foo property",
      "readOnly": true,
      "type": "number"
    },
    "bar": {
      "description": "bar property",
      "type": "boolean"
    }
  }
}

This utility lets you do that:

var deref = require('json-schema-deref');
var myschema = require('schema.json');

deref(myschema, function(err, fullSchema) {
  console.dir(fullSchema); // has the full expanded $refs
});

API Reference

deref(schema, options, fn)

Derefs $ref's in JSON Schema to actual resolved values. Supports local, file and web refs.

Kind: global function

Param	Type	Description
schema	`Object`	The JSON schema
options	`Object`	options
options.baseFolder	`String`	the base folder to get relative path files from. Default is `process.cwd()`
options.cache	`String`	whether to cache the result from the request. Default: `true`.
options.cacheTTL	`Number`	the time to keep request result in cache. Default is `5 minutes`.
options.failOnMissing	`Boolean`	By default missing / unresolved refs will be left as is with their ref value intact. If set to `true` we will error out on first missing ref that we cannot resolve. Default: `false`.
options.loader	`function`	a function for custom loader. Invoked if we could not resolve the ref type, or if there was an error resolving a web or file ref types. function with signature: `function(refValue, options, fn)` `refValue` - the string value of the ref being resolved. Ex: `db://my_database_id` `options` - options parameter passed to `deref` `fn` - the final callback function, in form `function(err, newValue)` `err` - error if ref is valid for the loader but there was an error resolving the ref. If used in combination with `failOnMissing` option it will abort the whole deref process. `newValue` - the resolved ref value, or `null` or `undefined` if the ref isn't for this custom `loader` and we should just leave the `$ref` as is.
options.mergeAdditionalProperties	`Boolean`	By default properties in a object with $ref will be removed in the output. If set to `true` they will be added/overwrite the output. Default: `false`.
options.removeIds	`Boolean`	By default `$id` fields will get copied when dereferencing. If set to `true` they will be removed. Default: `false`.
fn	`function`	The final callback in form `(error, newSchema)`

Custom Loader

Let's say we want to get $ref's from a MongoDB database, and our $ref objects in the JSON Schema might be something like:

"foo": {
  "$ref":"mongodb:507c35dd8fada716c89d0013"
}

Our custom loader function passed in the options loader parameter would look something like: