json-deref

[WIP] json-deref

Dereference JSON-reference in a JSON document

Installation

npm install json-deref

Overview

Let's say you have the following JSON Schema:

{
  "description": "Just some JSON schema.",
  "title": "Basic Widget",
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/definitions/id"
    },
    "foo": {
      "$ref": "#/definitions/foo"
    },
    "bar": {
      "$ref": "bar.json"
    }
  },
  "definitions": {
    "id": {"$ref": "common-definitions.json#definitions/id"},
    "foo": {"$ref": "common-definitions.json#definitions/foo"}
  }

}

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",
  "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"
    }
  },
  "definitions": {
    "id": {
      "description": "unique identifier",
      "type": "string",
      "minLength": 1,
      "readOnly": true
    },
    "foo": {
      "description": "foo property",
      "readOnly": true,
      "type": "number"
    }
  }

}

or you could also just want to parse external references

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

}

This utility lets you do that:

import deref from 'json-deref'
import mySchema from 'schema.json'

deref(mySchema).then(fullSchema => {
  console.dir(fullSchema) // the fully parsed schema
})

deref(mySchema, {externalOnly: true}).then(onlyLocals => {
  console.dir(onlyLocals) // only external refs parsed
})

API Reference

deref(schema, options, fn)

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

Param	Type	Description
schema	Object / string	The schema object or schema url
options	Object	options
options.baseURL	String	url base in case schema object doesn't define $id
options.cache	boolean / object	Defines wheather cache is used or explicitly sets it. Default: false.
options.cacheTTL	number	Cache max-age (todo)
options.loaders	object	Object whose key name defines loader protocol to override/add and value is the loader function called with arguments (url, defaultLoader).
options.externalOnly	Boolean	If true local references are left intact. Default: false.