Registry / devops / json-schema-deref

json-schema-deref

JSON →
library0.5.0jsnpmunverified

Synchronous and async JSON Schema $ref dereferencing library for Node.js. Version 0.5.0 resolves local, file, and web references in JSON Schema objects by replacing $ref pointers with their resolved values. Unlike alternatives like json-schema-ref-parser, it offers a simpler API and optional caching of remote refs. Includes TypeScript types. Primarily maintained for legacy Node.js (>=6.0.0) projects; newer work is on json-schema-deref-sync. Release cadence is low; no recent updates.

devops
npm install json-schema-deref
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · JSON-SCHEMA-DEREF
J
json-schema-deref
devopsjavascriptv0.5.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.

deref
✓ const deref = require('json-schema-deref');
✗ import deref from 'json-schema-deref';
Package uses CommonJS; no default ES module export. Use require().
deref (callback)
✓ deref(schema, function(err, result) { ... });
✗ const result = deref(schema);
deref is async (callback-based); does not return a value. Use callback or promisify it.
deref (promisify)
✓ const { promisify } = require('util'); const derefAsync = promisify(require('json-schema-deref'));
Promisification is common for async/await usage. Package does not provide a promise-based API natively.

Resolves a simple local $ref in a JSON Schema using the callback-based API with minimal options.

const deref = require('json-schema-deref'); const schema = { type: 'object', properties: { name: { $ref: '#/definitions/name' } }, definitions: { name: { type: 'string' } } }; deref(schema, { cache: false, failOnMissing: true }, (err, fullSchema) => { if (err) throw err; console.log(JSON.stringify(fullSchema, null, 2)); });
Debug
Known issues
breakingRequires Node.js >= 6.0.0; may not work on older versions.
fix
Upgrade Node.js to >=6.0.0 or use a compatible version of the package.
affects: <0.5.0
deprecatedThe `request` dependency is deprecated and unmaintained. This may cause security vulnerabilities or compatibility issues.
fix
Switch to json-schema-deref-sync for local schemas, or fork/monkey-patch with a different HTTP library (e.g., node-fetch).
affects: >=0.1.0
gotchaRemote $ref resolution may be slow or fail if network requests are blocked. The library uses request's default timeout (no timeout).
fix
Implement a custom loader with your own timeout/retry logic via the `loader` option, or pre-fetch schemas.
affects: >=0.1.0
breakingCallback is mandatory; calling without callback will throw an error.
fix
Always provide a callback function as the third argument.
affects: >=0.1.0
gotchaCaching is enabled by default (cache: true) with 5-minute TTL. Remote schema changes may not be reflected if cached.
fix
Set options.cache = false or adjust cacheTTL to a smaller value for fresh results.
affects: >=0.1.0
breakingIf a $ref cannot be resolved and failOnMissing is false (default), the $ref is left in place as a string, which can cause unexpected schema behavior.
fix
Set failOnMissing: true to error out on unresolvable refs, or explicitly handle unresolved refs in the result.
affects: >=0.1.0
Errors
Common errors & fixes
TypeError: deref is not a function
Using ES import syntax with a CommonJS module.
fix
Use const deref = require('json-schema-deref'); instead of import statements.
Error: Cannot find module 'request'
request is an optional dependency but not installed; may be missing if using npm --no-optional.
fix
Run `npm install request` to install request, or use the library without remote schemas (local $refs only).
Unhandled 'error' event: Error: connect ECONNREFUSED
Remote schema server is unreachable or network is blocked.
fix
Check network connectivity, use a custom loader that handles errors, or pre-fetch the remote schema.
Upgrade
Version history
0.5.0latest on npm
Audit
Dependencies
asyncrequiredUsed for asynchronous control flow (waterfall, map), especially when resolving multiple $refs concurrently.
requestoptionalUsed for fetching remote JSON Schema files over HTTP/HTTPS. Note: request is deprecated.
Agent activity
12 hits · last 30 days
node
10
Perplexity
1
Resources
githubgit://github.com/bojand/json-schema-deref ↗
packagejson-schema-deref ↗
homepagehttps://github.com/bojand/json-schema-deref ↗