JSON Reference and Pointer Utilities

Common errors

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

  cause 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)

  cause 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.

  cause 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.

Warnings

• breaking The `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.
• breaking The 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.
• breaking Versions 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.

Install

• npm install json-refs npm
• yarn add json-refs yarn
• pnpm add json-refs pnpm

Imports

• jsonRefs
  wrong:

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

  correct:

  import jsonRefs from 'json-refs';

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

  import { resolveRefs } from 'json-refs';

  correct:

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

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

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

  correct:

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

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

Quickstart

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);
  });