Registry / storage / json-schema-deref-sync

json-schema-deref-sync

JSON →
library0.14.0jsnpmunverified

A synchronous Node.js library to dereference $ref pointers in JSON Schema documents, resolving local and file-based references to their actual values. Current stable version is 0.14.0, with low release cadence (last update in 2019). It is a lighter alternative to json-schema-deref, omitting web references and working synchronously. Useful for expanding JSON Schemas at build time or in synchronous contexts. Supports options like baseFolder, failOnMissing, mergeAdditionalProperties, removeIds, and custom loaders.

storage
npm install json-schema-deref-sync
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · JSON-SCHEMA-DEREF-
J
json-schema-deref-sync
storagejavascriptv0.14.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-sync');
✗ import deref from 'json-schema-deref-sync';
Package is CommonJS only. ES import not available.
deref
✓ const deref = require('json-schema-deref-sync').default;
Some users mistakenly use .default on the result. The package exports the function directly, not as default export.
deref
✓ import * as deref from 'json-schema-deref-sync';
✗ import deref from 'json-schema-deref-sync';
In TypeScript with esModuleInterop, default import may work, but namespace import is safer.

Demonstrates synchronous dereferencing of local $ref and file $ref with options.

const deref = require('json-schema-deref-sync'); const schema = { definitions: { id: { type: 'string', minLength: 1 } }, properties: { id: { $ref: '#/definitions/id' }, bar: { $ref: 'bar.json' } } }; // Optionally set options.baseFolder for relative file refs const fullSchema = deref(schema, { baseFolder: __dirname, failOnMissing: false }); console.log(fullSchema);
Debug
Known issues
gotchaPackage does not dereference web references (http://, https://). Only local references (#/definitions/...) and file references (./file.json) are supported.
fix
Use json-schema-deref (async) if web dereferencing is needed.
affects: >=0.0.0
breakingIn version 0.6.0, the function signature changed from deref(schema, options, callback) to deref(schema, options) returning value or Error (synchronous). Callback is no longer supported.
fix
Remove callback and handle returned value or Error with try/catch.
affects: >=0.6.0
gotchaBy default, properties alongside a $ref in an object are removed. Setting mergeAdditionalProperties: true will merge them, but this uses lodash.merge and may have unexpected deep merge behavior.
fix
Set mergeAdditionalProperties: true if you want to keep sibling properties, and review lodash.merge documentation.
affects: >=0.0.0
gotchaOptions.removeIds will remove $id fields from the output schema but not from merged properties. This can lead to inconsistent schema results.
fix
Be aware of this behavior; manually clean up IDs after dereferencing if needed.
affects: >=0.0.0
gotchaWhen failOnMissing is false (default), unresolved $ref remain as-is (e.g., { $ref: 'missing.json' }). This may cause downstream issues if schema consumers expect fully dereferenced schemas.
fix
Set failOnMissing: true to throw an error on unresolvable refs.
affects: >=0.0.0
Errors
Common errors & fixes
TypeError: deref(...) is not a function
Using ES import syntax with default import on a CommonJS module that exports the function directly.
fix
Use `const deref = require('json-schema-deref-sync');` or `import * as deref from 'json-schema-deref-sync';`
Error: Cannot resolve ref: http://example.com/schema.json
Attempting to dereference a web URI, which is not supported by this package.
fix
Use json-schema-deref (async) or download the schema locally first.
Cannot read property 'then' of undefined
Using deref() with .then() expecting a Promise, but it returns synchronously.
fix
Use the result directly: `const result = deref(schema, options);`
UnhandledPromiseRejectionWarning: Error: Missing schema reference: missing.json
A file reference could not be resolved and failOnMissing is true.
fix
Ensure the referenced file exists or set failOnMissing: false to keep the unresolved ref.
Upgrade
Version history
0.14.0latest on npm
Audit
Dependencies
json-schema-deref-syncrequiredThe package itself is the primary dependency for dereferencing.
debugoptionalUsed internally for logging; may be installed as a dependency.
lodashoptionalUsed for option mergeAdditionalProperties; required if that option is used.
Agent activity
17 hits · last 30 days
node
16
Resources
githubgit://github.com/cvent/json-schema-deref-sync ↗
packagejson-schema-deref-sync ↗
homepagehttps://github.com/cvent/json-schema-deref-sync ↗
json-schema-deref-sync — npm install json-schema-deref-sync · libregistry