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

npm install json-schema-ref-resolver

Usage

const assert = require('node:assert')
const { RefResolver } = require('json-schema-ref-resolver')

const sourceSchema = {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      $ref: 'targetSchema#/definitions/bar'
    }
  }
}

const targetSchema = {
  $id: 'targetSchema',
  definitions: {
    bar: {
      type: 'string'
    }
  }
}

const refResolver = new RefResolver()

refResolver.addSchema(sourceSchema)
refResolver.addSchema(targetSchema)

const derefSourceSchema = refResolver.getDerefSchema('sourceSchema')
assert.deepStrictEqual(derefSourceSchema, {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      type: 'string'
    }
  }
})

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:

const assert = require('node:assert')
const { RefResolver } = require('json-schema-ref-resolver')

const schema = {
  $id: 'schema',
  type: 'object',
  properties: {
    foo: { type: 'string' }
  }
}

const refResolver = new RefResolver()
refResolver.addSchema(schema)

const rootSchema = refResolver.getSchema(schema.$id)
assert.deepStrictEqual(rootSchema, schema)

const subSchema = refResolver.getSchema(schema.$id, '#/properties/foo')
assert.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:

const assert = require('node:assert')
const { RefResolver } = require('json-schema-ref-resolver')

const schema = {
  $id: 'schema',
  definitions: {
    bar: {
      $id: '#bar',
      type: 'string'
    }
  }
}

const refResolver = new RefResolver()
refResolver.addSchema(schema)

const anchorSchema = refResolver.getSchema(schema.$id, '#bar')
assert.deepStrictEqual(subSchema, {
  $id: '#bar',
  type: 'string'
})

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:

const assert = require('node:assert')

const { RefResolver } = require('json-schema-ref-resolver')

const sourceSchema = {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      $ref: 'targetSchema#/definitions/bar'
    },
    baz: {
      $ref: 'targetSchema#/definitions/qux'
    }
  }
}

const refResolver = new RefResolver()
refResolver.addSchema(sourceSchema)

const refs = refResolver.getSchemaRefs('sourceSchema')
assert.deepStrictEqual(refs, [
  {
    schemaId: 'targetSchema',
    jsonPointer: '#/definitions/bar'
  },
  {
    schemaId: 'targetSchema',
    jsonPointer: '#/definitions/qux'
  }
])

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:

const assert = require('node:assert')

const { RefResolver } = require('json-schema-ref-resolver')

const targetSchema1 = {
  $id: 'targetSchema1',
  definitions: {
    bar: { type: 'string' }
  }
}

const targetSchema2 = {
  $id: 'targetSchema2',
  type: 'object',
  properties: {
    qux: { $ref: 'targetSchema1' }
  }
}

const sourceSchema = {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: { $ref: 'targetSchema2' }
  }
}

const refResolver = new RefResolver()

refResolver.addSchema(sourceSchema)
refResolver.addSchema(targetSchema1)
refResolver.addSchema(targetSchema2)

const dependencies = refResolver.getSchemaDependencies('sourceSchema')
assert.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

const assert = require('node:assert')
const { RefResolver } = require('json-schema-ref-resolver')

const sourceSchema = {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      $ref: 'targetSchema#/definitions/bar'
    }
  }
}

const targetSchema = {
  $id: 'targetSchema',
  definitions: {
    bar: {
      type: 'string'
    }
  }
}

const refResolver = new RefResolver()

refResolver.addSchema(sourceSchema)
refResolver.addSchema(targetSchema)

refResolver.derefSchema('sourceSchema')
const derefSourceSchema = refResolver.getDerefSchema('sourceSchema')

assert.deepStrictEqual(derefSourceSchema, {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      type: 'string'
    }
  }
})

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:

const assert = require('node:assert')
const { RefResolver } = require('json-schema-ref-resolver')

const sourceSchema = {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      $ref: 'targetSchema#/definitions/bar'
    }
  }
}

const targetSchema = {
  $id: 'targetSchema',
  definitions: {
    bar: {
      type: 'string'
    }
  }
}

const refResolver = new RefResolver()

refResolver.addSchema(sourceSchema)
refResolver.addSchema(targetSchema)

const derefSourceSchema = refResolver.getDerefSchema('sourceSchema')
assert.deepStrictEqual(derefSourceSchema, {
  $id: 'sourceSchema',
  type: 'object',
  properties: {
    foo: {
      type: 'string'
    }
  }
})

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:

const assert = require('node:assert')
const { RefResolver } = require('json-schema-ref-resolver')

const targetSchema = {
  $id: 'targetSchema',
  definitions: {
    bar: {
      type: 'object',
      properties: {
        foo: { type: 'string' }
      }
    }
  }
}

const sourceSchema = {
  $id: 'sourceSchema',
  type: 'object',
  $ref: 'targetSchema#/definitions/bar'
  properties: {
    foo: { type: 'number' }
  }
}

const refResolver = new RefResolver()
refResolver.addSchema(targetSchema)
refResolver.addSchema(sourceSchema)

refResolver.derefSchema('sourceSchema') // Throws an error