Registry / development / json-schema-ref-resolver

json-schema-ref-resolver

library3.0.0jsnpmunverified

JavaScript library that resolves $ref references in JSON Schemas, part of the Fastify ecosystem. Current stable version is 3.0.0, released with TypeScript type definitions and following semver. It resolves internal and external schema references, supports dereferencing, and provides schema dependency tracking. Unlike json-schema-ref-parser, it is lightweight, synchronous, and focused on Fastify-like use cases. Key differentiators: no dependencies, simple API, and support for circular references with optional Symbol insertion.

development testing

npm install json-schema-ref-resolver

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JSON-SCHEMA-REF-RE

json-schema-ref-resolver

developmentjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

RefResolver

✓ import { RefResolver } from 'json-schema-ref-resolver'

✗ import RefResolver from 'json-schema-ref-resolver'

ESM default import is incorrect; named export only.

RefResolver

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

CJS destructured require is the traditional usage.

RefResolver

✓ import { RefResolver } from 'json-schema-ref-resolver'

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

CJS require on the default export does not work; use destructuring.

Demonstrates adding two schemas (one referencing the other via $ref), then retrieving the dereferenced schema where the reference is replaced by the actual type.

import { RefResolver } from 'json-schema-ref-resolver'; const refResolver = new RefResolver(); refResolver.addSchema({ $id: 'example', type: 'object', properties: { name: { $ref: 'common#/definitions/name' } } }); refResolver.addSchema({ $id: 'common', definitions: { name: { type: 'string' } } }); const derefed = refResolver.getDerefSchema('example'); console.log(derefed); // { $id: 'example', type: 'object', properties: { name: { type: 'string' } } }

Debug

Known issues

gotchaBy default, addSchema() does not throw when schemas with duplicate $id are added; it only throws if they are not equal.

fix

Set allowEqualDuplicates: false in constructor options to enforce strict unique $id.

affects: >=1.0.0

gotchagetSchema() throws an error if the schemaId is not found, but returns null if jsonPointer is provided and the pointer resolves to nothing.

fix

Wrap getSchema() calls in try/catch when not using jsonPointer, or always provide jsonPointer and check for null.

affects: >=1.0.0

deprecatedThe 'allowEqualDuplicates' option default changed from undefined to true in v3, allowing duplicate $id by default.

fix

If you rely on strict schema id uniqueness, explicitly set allowEqualDuplicates: false.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: RefResolver is not a constructor

Importing the module incorrectly, e.g., using default import in ESM or requiring without destructuring.

fix

Use import { RefResolver } from 'json-schema-ref-resolver' in ESM, or const { RefResolver } = require('json-schema-ref-resolver') in CJS.

Error: Schema with id "..." is already added

Attempting to add a schema with a duplicate $id and allowEqualDuplicates is false (or schemas are not equal).

fix

Ensure unique $id values per schema, or set allowEqualDuplicates: true in the constructor (default).

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/fastify/json-schema-ref-resolver ↗

packagejson-schema-ref-resolver ↗

homepagehttps://github.com/fastify/json-schema-ref-resolver#readme ↗