json-refs

library3.0.15jsnpmunverified

json-refs is a JavaScript library providing comprehensive utilities for interacting with JSON References (based on draft-pbryan-zyp-json-ref-03) and JSON Pointers (RFC6901). Its primary function is to resolve references within JSON documents, making it highly valuable for managing complex data structures such as OpenAPI/Swagger definitions, JSON Schemas, or any document with interlinked parts. The current stable version is 3.0.15. While a strict release cadence is not explicitly defined, the project shows active maintenance, including significant breaking changes in v3.0.0 and critical security patches in v2.1.7. A key differentiator is its dual focus on both JSON Reference and JSON Pointer specifications, offering robust solutions for Node.js and browser environments, complete with TypeScript type definitions.

serialization data web-framework

npm install json-refs

github ↗package ↗

INSTALL

IMPORT

SIG · JSON-REFS

json-refs

serializationjavascriptv3.0.15

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

jsonRefs

✓ import jsonRefs from 'json-refs';

✗ const jsonRefs = require('json-refs');

While originally a CommonJS module, TypeScript definition files allow ESM-style default imports which transpile correctly. For strict CommonJS, use `require`.

resolveRefs

✓ import jsonRefs from 'json-refs'; jsonRefs.resolveRefs(root, options);

✗ import { resolveRefs } from 'json-refs';

The library exports a single default object containing all its methods, rather than named exports for individual functions.

findRefs

✓ import jsonRefs from 'json-refs'; jsonRefs.findRefs(root, options);

✗ const findRefs = require('json-refs').findRefs;

All functions are properties of the default exported object. Direct destructuring from `require()` or named ESM imports are incorrect.

Demonstrates how to resolve JSON References within a document, including local, relative, and external references.

import jsonRefs from 'json-refs'; const documentWithRefs = { a: 'Hello', b: { $ref: '#/a' }, c: { $ref: 'external.json#/message' }, d: { $ref: 'https://example.com/api/spec.json#/paths/~1users' } }; const options = { // For demonstration, mock a simple external file. // In a real application, you'd use a loader for 'external.json'. loaderOptions: { processContent: function (res, callback) { if (res.url.endsWith('external.json')) { callback(null, { text: JSON.stringify({ message: 'World from external!' }) }); } else { callback(null, res.text); } } }, // Important for resolving relative references like 'external.json' location: 'file:///path/to/base/document.json' // Replace with actual base URI if needed }; jsonRefs.resolveRefs(documentWithRefs, options) .then(function (res) { console.log('Resolved Document:', JSON.stringify(res.resolved, null, 2)); console.log('Unresolved References:', res.unresolved); }) .catch(function (err) { console.error('Error resolving references:', err); });

Debug

Known issues

breakingThe `options.relativeBase` property has been removed. Users should now use `options.location` to specify the base URI for resolving relative references.

fix

Replace `options.relativeBase` with `options.location` in your configuration objects, providing the URI of the document being resolved.

affects: >=3.0.0

breakingThe behavior for resolving circular references has changed significantly. Previously, all references to circular paths were unresolved. Now, if `options.resolveCirculars` is `false` (which is the default), references to circular paths will only be resolved if the reference location itself is not circular.

fix

If you require full resolution of circular references, set `options.resolveCirculars` to `true`. Otherwise, review your handling of circular structures to account for the new default behavior.

affects: >=3.0.0

breakingVersions prior to `v2.1.7` contained security vulnerabilities due to insecure versions of internal dependencies (`qs` and `uri-js`) used by `path-loader`. These issues could potentially lead to denial of service or other exploits.

fix

Upgrade to `json-refs@2.1.7` or newer immediately to mitigate these security risks. All dependencies were updated in this release to address the vulnerabilities.

affects: <2.1.7

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'resolveRefs') OR TypeError: jsonRefs.resolveRefs is not a function

Incorrect import statement for a CommonJS module in an environment expecting ESM, or attempting to destructure from the main export.

fix

For TypeScript or modern JavaScript with transpilation, use `import jsonRefs from 'json-refs';`. For pure CommonJS, use `const jsonRefs = require('json-refs');`. Do not use named imports like `import { resolveRefs } from 'json-refs';`.

Error: Could not resolve reference: ... (followed by a path)

The specified JSON reference path is invalid, the referenced document cannot be found, or `options.location` is not correctly configured for relative references, especially after upgrading to v3.0.0.

fix

Verify the JSON Pointer path within the reference. Ensure all external files or URLs are accessible. If using relative paths, set `options.location` to the base URI of the document containing the reference. Remember `options.relativeBase` was removed in v3.0.0.

Circular reference detection (or lack thereof) leading to unexpected output or infinite loops.

Behavior for circular reference resolution changed in v3.0.0. The default `options.resolveCirculars` is `false`, meaning circular references are handled differently than in previous versions.

fix

Explicitly set `options.resolveCirculars: true` if you intend to fully resolve all circular references, but be cautious of potential performance or output size issues. Otherwise, understand that circular paths might not be fully resolved by default.

Upgrade

Version history

3.0.15latest on npm

Audit

Dependencies

path-loaderrequiredInternal dependency for loading paths, historically involved in security advisories.

uri-jsrequiredInternal dependency for URI parsing and manipulation, historically involved in security advisories.

qsrequiredQuery string parser used by path-loader, historically involved in security advisories.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/whitlockjc/json-refs ↗

packagehttps://www.npmjs.com/package/json-refs ↗