eomm / json-schema-resolver

Resolve all your JSON Schema $refs to relative path

json-schema-resolver

Resolve all $refs in your JSON schema!
This module will resolve the $ref keyword against the externalSchemas you will provide.
By resolving the $ref keyword, means that you get back a single BIG inlined JSON schema that does not rely on any external schema. If a reference is missing, it will not throw any error.

Install

npm install json-schema-resolver

This plugin support Node.js >= 10

Usage: resolve one schema against external schemas

The $ref string is going to be modified to point to a local reference URI: #/definitions/<generated key>. Moreover, the definitions keyword will be decorated with the external schemas to get only one JSON schema resolved as output.

By default the <generated key> has the def-${index} format. You can customize it by passing a buildLocalReference function as follows:

const RefResolver = require('json-schema-resolver')

const ref = RefResolver({
  clone: true, // Clone the input schema without changing it. Default: false,
  buildLocalReference (json, baseUri, fragment, i) {
    // the `json` that is being resolved
    // the `baseUri` object of the schema. Its values is the parse result from https://www.npmjs.com/package/uri-js
    // the `fragment` is the `$ref` string when the `$ref` is a relative reference
    // the `i` is a local counter to generate a unique key
    return `def-${i}` // default value
  }
})

const inputSchema = {
  $id: 'http://example.com/SimplePerson',
  type: 'object',
  properties: {
    name: { type: 'string' },
    address: { $ref: 'relativeAddress#' },
    houses: { type: 'array', items: { $ref: 'relativeAddress#' } }
  }
}

const addresSchema = {
  $id: 'relativeAddress', // Note: prefer always absolute URI like: http://mysite.com
  type: 'object',
  properties: {
    zip: { type: 'string' },
    city: { type: 'string' }
  }
}

const singleSchema = ref.resolve(inputSchema, { externalSchemas: [addresSchema] })
// inputSchema is untouched thanks to clone:true

singleSchema will be like:

{
  "$id": "http://example.com/SimplePerson",
  "type": "object",
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/definitions/def-0"
    },
    "houses": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/def-0"
      }
    }
  },
  "definitions": {
    "def-0": {
      "$id": "relativeAddress",
      "type": "object",
      "properties": {
        "zip": {
          "type": "string"
        },
        "city": {
          "type": "string"
        }
      }
    }
  }
}

Usage: resolve multiple schemas against external shared schemas

When you have multiple schemas to resolve against a collection of shared schema you need to use this module with little changes.

This is needed to have all the same definitions path (#/definitions/<generated key>) across all the root schemas

const ref = RefResolver({
  clone: true, // Clone the input schema without changing it. Default: false
  applicationUri: 'my-application.org', // You need to provide an unique URI to resolve relative `$id`s
  externalSchemas: [addresSchema] // The schemas provided at the creation of the resolver, will be used evvery time `.resolve` will be called
})

const inputSchema = {
  $id: 'http://example.com/SimplePerson',
  type: 'object',
  properties: {
    name: { type: 'string' },
    address: { $ref: 'relativeAddress#' },
    houses: { type: 'array', items: { $ref: 'relativeAddress#' } }
  }
}

// the resolved schema DOES NOT have definitions added
const singleSchema = ref.resolve(inputSchema)
const anotherResolvedSchema = ref.resolve(input_2_Schema) // resolve schemas within the same externalSchemas

// to get the definition you need only to call:
const sharedDefinitions = ref.definitions()

Debug

To debug this module, simply set:

export DEBUG=json-schema-resolver

License

Licensed under MIT.

json-schema-resolver's Issues

Local references in external schemas are not resolved.

    const resolvedSchema = resolver.resolve(
        {
            "$id": "test",
            "title": "Test",
            "type": "object",
            "properties": {
                "TestString": { "$ref": "DefSchema#/$defs/Username" }
            }                      
        }, 
        {
            externalSchemas: [
                {
                    "$id": "DefSchema",
                    "$defs": {
                        "Username": { "$ref": "#/$defs/string:10" },
                        "string:10": {
                            "type": "string",
                            "maxLength": 10
                        }
                    }
                }
            ]
        }
    )

Produces the following incorrect reference:

{
  "$id": "test",
  "definitions": {
     "def-0": {
      "$defs": {
        "Username": { "$ref": "#/$defs/string:10" }
      }
    }
  }
}

As opposed to the expected:

{
  "$id": "test",
  "definitions": {
     "def-0": {
      "$defs": {
        "Username": { "$ref": "#/definitions/def-0/$defs/string:10" }
      }
    }
  }
}