json-deref v1.1.0

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.