Synchronous JSON schema dereference utility that supports any file format
Clone or download
Pull request Compare This branch is 4 commits ahead, 26 commits behind bojand:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib
test
.babelrc
.eslintignore
.gitignore
.npmignore
ISSUE_TEMPLATE.md
LICENSE
LICENSE.txt
README.md
package.json
readme.hbs

README.md

Agnostic Dereference

Dereference JSON pointers in a JSON schemas with their true resolved values. A custom parsing function can be specified to support dereferencing of any file format. This has been forked from json-schema-deref.

Installation

npm install agnostic-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('agnostic-deref');
var myschema = require('schema.json');

var fullSchema = deref(myschema);

Agnostic Deference also allows refs of any format to be parsed via the options.parser function. This is useful if you specify your schemas in a non-JSON format, such as YAML:

# schema.yaml
---
  description: User
  title: User
  type: object

  properties:
    subschema:
      $ref: subschema.yaml

# subschema.yaml
---
  description: "Some subschema"
  properties:
    foo:
      type: string
    bar:
      type: object
const yaml = require('js-yaml');
const deref = require('agnostic-deref');
const fs = require('fs');

const schema = yaml.safeLoad(fs.readFileSync('schema.yaml'));

const fullSchema = deref(schema, { parser: yaml.safeLoad });

API Reference

deref(schema, options) ⇒ Object | Error

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

Kind: global function Returns: Object | Error - the deref schema oran instance of Error if error.

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.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.parser Function The function invoked to parse the contents of files located at each $ref. This defaults to JSON.parse.