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

1npm 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:

1const RefResolver = require('json-schema-resolver')
2
3const ref = RefResolver({
4  clone: true, // Clone the input schema without changing it. Default: false,
5  buildLocalReference (json, baseUri, fragment, i) {
6    // the `json` that is being resolved
7    // the `baseUri` object of the schema. Its values is the parse result from https://www.npmjs.com/package/fast-uri
8    // the `fragment` is the `$ref` string when the `$ref` is a relative reference
9    // the `i` is a local counter to generate a unique key
10    return `def-${i}` // default value
11  }
12})
13
14const inputSchema = {
15  $id: 'http://example.com/SimplePerson',
16  type: 'object',
17  properties: {
18    name: { type: 'string' },
19    address: { $ref: 'relativeAddress#' },
20    houses: { type: 'array', items: { $ref: 'relativeAddress#' } }
21  }
22}
23
24const addresSchema = {
25  $id: 'relativeAddress', // Note: prefer always absolute URI like: http://mysite.com
26  type: 'object',
27  properties: {
28    zip: { type: 'string' },
29    city: { type: 'string' }
30  }
31}
32
33const singleSchema = ref.resolve(inputSchema, { externalSchemas: [addresSchema] })
34// inputSchema is untouched thanks to clone:true

singleSchema will be like:

1{
2  "$id": "http://example.com/SimplePerson",
3  "type": "object",
4  "properties": {
5    "name": {
6      "type": "string"
7    },
8    "address": {
9      "$ref": "#/definitions/def-0"
10    },
11    "houses": {
12      "type": "array",
13      "items": {
14        "$ref": "#/definitions/def-0"
15      }
16    }
17  },
18  "definitions": {
19    "def-0": {
20      "$id": "relativeAddress",
21      "type": "object",
22      "properties": {
23        "zip": {
24          "type": "string"
25        },
26        "city": {
27          "type": "string"
28        }
29      }
30    }
31  }
32}

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

1const ref = RefResolver({
2  clone: true, // Clone the input schema without changing it. Default: false
3  applicationUri: 'my-application.org', // You need to provide an unique URI to resolve relative `$id`s
4  externalSchemas: [addresSchema] // The schemas provided at the creation of the resolver, will be used evvery time `.resolve` will be called
5})
6
7const inputSchema = {
8  $id: 'http://example.com/SimplePerson',
9  type: 'object',
10  properties: {
11    name: { type: 'string' },
12    address: { $ref: 'relativeAddress#' },
13    houses: { type: 'array', items: { $ref: 'relativeAddress#' } }
14  }
15}
16
17// the resolved schema DOES NOT have definitions added
18const singleSchema = ref.resolve(inputSchema)
19const anotherResolvedSchema = ref.resolve(input_2_Schema) // resolve schemas within the same externalSchemas
20
21// to get the definition you need only to call:
22const sharedDefinitions = ref.definitions()

Debug

To debug this module, simply set:

1export DEBUG=json-schema-resolver

License

Licensed under MIT.