json-schema-ref-resolver

json-schema-ref-resolver is a javascript library that resolves references in JSON schemas.

• Installation
• Usage
• API
  • RefResolver([options])
  • addSchema(schema, [schemaId])
  • getSchema(schemaId, [jsonPointer])
  • getSchemaRefs(schemaId)
  • getSchemaDependencies(schemaId)
  • derefSchema(schemaId)
  • getDerefSchema(schemaId, [jsonPointer])
• Caveats

Installation

1npm install json-schema-ref-resolver

Usage

1const assert = require('node:assert')
2const { RefResolver } = require('json-schema-ref-resolver')
3
4const sourceSchema = {
5  $id: 'sourceSchema',
6  type: 'object',
7  properties: {
8    foo: {
9      $ref: 'targetSchema#/definitions/bar'
10    }
11  }
12}
13
14const targetSchema = {
15  $id: 'targetSchema',
16  definitions: {
17    bar: {
18      type: 'string'
19    }
20  }
21}
22
23const refResolver = new RefResolver()
24
25refResolver.addSchema(sourceSchema)
26refResolver.addSchema(targetSchema)
27
28const derefSourceSchema = refResolver.getDerefSchema('sourceSchema')
29assert.deepStrictEqual(derefSourceSchema, {
30  $id: 'sourceSchema',
31  type: 'object',
32  properties: {
33    foo: {
34      type: 'string'
35    }
36  }
37})

API

RefResolver([options])

• allowEqualDuplicates - if set to false, an error will be thrown if a schema with the same $id is added to the resolver. If set to true, the error will be thrown only if the schemas are not equal. Default: true.

• insertRefSymbol - if set to true resolver inserts a Symbol.for('json-schema-ref') instead of the $ref property when dereferencing a schema. Default false.

• cloneSchemaWithoutRefs - if set to false resolver would not clone a schema if it does not have references. That allows to significantly improve performance when dereferencing a schema. If you want to modify a schema after dereferencing, set this option to true. Default: false.

addSchema(schema, [schemaId])

Adds a json schema to the resolver. If the schema has an $id property, it will be used as the schema id. Otherwise, the schemaId argument will be used as the schema id. During the addition of the schema, ref resolver will find and add all nested schemas and references.

• schema <object> - json schema to add to the resolver.
• schemaId <string> - schema id to use. Will be used only if the schema does not have an $id property.

getSchema(schemaId, [jsonPointer])

Returns a json schema by its id. If the jsonPointer argument is provided, ref resolver will return the schema at the specified json pointer location.

If shema with the specified id is not found, an error will be thrown. If the jsonPointer argument is provided and the schema at the specified location is not found, getSchema will return null.

• schemaId <string> - schema id of the schema to return.
• jsonPointer <string> - json pointer to the schema location.
• Returns - json schema or null if the schema at the specified location is not found.

Example:

1const assert = require('node:assert')
2const { RefResolver } = require('json-schema-ref-resolver')
3
4const schema = {
5  $id: 'schema',
6  type: 'object',
7  properties: {
8    foo: { type: 'string' }
9  }
10}
11
12const refResolver = new RefResolver()
13refResolver.addSchema(schema)
14
15const rootSchema = refResolver.getSchema(schema.$id)
16assert.deepStrictEqual(rootSchema, schema)
17
18const subSchema = refResolver.getSchema(schema.$id, '#/properties/foo')
19assert.deepStrictEqual(subSchema, { type: 'string' })

getSchema can also be used to get a schema by its json schema anchor. To get schema by schema anchor, the schemaId argument must be set to the $id of the schema that contains the anchor, and the jsonPointer argument must be set to the anchor.

Example:

1const assert = require('node:assert')
2const { RefResolver } = require('json-schema-ref-resolver')
3
4const schema = {
5  $id: 'schema',
6  definitions: {
7    bar: {
8      $id: '#bar',
9      type: 'string'
10    }
11  }
12}
13
14const refResolver = new RefResolver()
15refResolver.addSchema(schema)
16
17const anchorSchema = refResolver.getSchema(schema.$id, '#bar')
18assert.deepStrictEqual(subSchema, {
19  $id: '#bar',
20  type: 'string'
21})

getSchemaRefs(schemaId)

Returns all references found in the schema during the addition of the schema to the resolver. If schema with the specified id is not found, an error will be thrown.

• schemaId <string> - schema id of the schema to return references for.
• Returns - array of objects with the following properties:
  • schemaId <string> - schema id of the reference.
  • jsonPointer <string> - json pointer of the reference.

If a reference does not have a schema id part, the schema id of the schema that contains the reference is used as the schema id of the reference.

Example:

1const assert = require('node:assert')
2
3const { RefResolver } = require('json-schema-ref-resolver')
4
5const sourceSchema = {
6  $id: 'sourceSchema',
7  type: 'object',
8  properties: {
9    foo: {
10      $ref: 'targetSchema#/definitions/bar'
11    },
12    baz: {
13      $ref: 'targetSchema#/definitions/qux'
14    }
15  }
16}
17
18const refResolver = new RefResolver()
19refResolver.addSchema(sourceSchema)
20
21const refs = refResolver.getSchemaRefs('sourceSchema')
22assert.deepStrictEqual(refs, [
23  {
24    schemaId: 'targetSchema',
25    jsonPointer: '#/definitions/bar'
26  },
27  {
28    schemaId: 'targetSchema',
29    jsonPointer: '#/definitions/qux'
30  }
31])

getSchemaDependencies(schemaId)

Returns all dependencies including nested dependencies found in the schema during the addition of the schema to the resolver. If schema with the specified id is not found, an error will be thrown.

• schemaId <string> - schema id of the schema to return dependencies for.
• Returns - an object with all found dependencies. The object keys are schema ids and the values are schema dependencies.

Example:

1const assert = require('node:assert')
2
3const { RefResolver } = require('json-schema-ref-resolver')
4
5const targetSchema1 = {
6  $id: 'targetSchema1',
7  definitions: {
8    bar: { type: 'string' }
9  }
10}
11
12const targetSchema2 = {
13  $id: 'targetSchema2',
14  type: 'object',
15  properties: {
16    qux: { $ref: 'targetSchema1' }
17  }
18}
19
20const sourceSchema = {
21  $id: 'sourceSchema',
22  type: 'object',
23  properties: {
24    foo: { $ref: 'targetSchema2' }
25  }
26}
27
28const refResolver = new RefResolver()
29
30refResolver.addSchema(sourceSchema)
31refResolver.addSchema(targetSchema1)
32refResolver.addSchema(targetSchema2)
33
34const dependencies = refResolver.getSchemaDependencies('sourceSchema')
35assert.deepStrictEqual(dependencies, { targetSchema1, targetSchema2 })

derefSchema(schemaId)

Dereferences all references in the schema. All dependency also will be dereferenced. If schema with the specified id is not found, an error will be thrown.

• schemaId <string> - schema id of the schema to dereference.

If a json schema has circular references or circular cross-references, dereferenced schema will have js circular references. Be careful when traversing the dereferenced schema.

Example

1const assert = require('node:assert')
2const { RefResolver } = require('json-schema-ref-resolver')
3
4const sourceSchema = {
5  $id: 'sourceSchema',
6  type: 'object',
7  properties: {
8    foo: {
9      $ref: 'targetSchema#/definitions/bar'
10    }
11  }
12}
13
14const targetSchema = {
15  $id: 'targetSchema',
16  definitions: {
17    bar: {
18      type: 'string'
19    }
20  }
21}
22
23const refResolver = new RefResolver()
24
25refResolver.addSchema(sourceSchema)
26refResolver.addSchema(targetSchema)
27
28refResolver.derefSchema('sourceSchema')
29const derefSourceSchema = refResolver.getDerefSchema('sourceSchema')
30
31assert.deepStrictEqual(derefSourceSchema, {
32  $id: 'sourceSchema',
33  type: 'object',
34  properties: {
35    foo: {
36      type: 'string'
37    }
38  }
39})

getDerefSchema(schemaId, [jsonPointer])

Returns a dereferenced schema by schema id and json pointer. If schema with the specified id is not found, an error will be thrown. If the jsonPointer argument is provided, ref resolver will return the schema at the specified json pointer location. If the jsonPointer argument is provided and the schema at the specified location is not found, getDerefSchema will return null.

If schema was not dereferenced before, it will be dereferenced during the call to getDerefSchema.

• schemaId <string> - schema id of the schema to return.
• jsonPointer <string> - json pointer to the schema location.
• Returns - dereferenced json schema or null if the schema at the specified location is not found.

Example:

1const assert = require('node:assert')
2const { RefResolver } = require('json-schema-ref-resolver')
3
4const sourceSchema = {
5  $id: 'sourceSchema',
6  type: 'object',
7  properties: {
8    foo: {
9      $ref: 'targetSchema#/definitions/bar'
10    }
11  }
12}
13
14const targetSchema = {
15  $id: 'targetSchema',
16  definitions: {
17    bar: {
18      type: 'string'
19    }
20  }
21}
22
23const refResolver = new RefResolver()
24
25refResolver.addSchema(sourceSchema)
26refResolver.addSchema(targetSchema)
27
28const derefSourceSchema = refResolver.getDerefSchema('sourceSchema')
29assert.deepStrictEqual(derefSourceSchema, {
30  $id: 'sourceSchema',
31  type: 'object',
32  properties: {
33    foo: {
34      type: 'string'
35    }
36  }
37})

Caveats

• If a reference schema and a source schema have a key with the same name and different values, an error will be throwing during a call to derefSchema or getDerefSchema.

Example:

1const assert = require('node:assert')
2const { RefResolver } = require('json-schema-ref-resolver')
3
4const targetSchema = {
5  $id: 'targetSchema',
6  definitions: {
7    bar: {
8      type: 'object',
9      properties: {
10        foo: { type: 'string' }
11      }
12    }
13  }
14}
15
16const sourceSchema = {
17  $id: 'sourceSchema',
18  type: 'object',
19  $ref: 'targetSchema#/definitions/bar'
20  properties: {
21    foo: { type: 'number' }
22  }
23}
24
25const refResolver = new RefResolver()
26refResolver.addSchema(targetSchema)
27refResolver.addSchema(sourceSchema)
28
29refResolver.derefSchema('sourceSchema') // Throws an error