{"id":17282,"library":"json-refs","title":"JSON Reference and Pointer Utilities","description":"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.","status":"active","version":"3.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/whitlockjc/json-refs","tags":["javascript","json","typescript"],"install":[{"cmd":"npm install json-refs","lang":"bash","label":"npm"},{"cmd":"yarn add json-refs","lang":"bash","label":"yarn"},{"cmd":"pnpm add json-refs","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Internal dependency for loading paths, historically involved in security advisories.","package":"path-loader","optional":false},{"reason":"Internal dependency for URI parsing and manipulation, historically involved in security advisories.","package":"uri-js","optional":false},{"reason":"Query string parser used by path-loader, historically involved in security advisories.","package":"qs","optional":false}],"imports":[{"note":"While originally a CommonJS module, TypeScript definition files allow ESM-style default imports which transpile correctly. For strict CommonJS, use `require`.","wrong":"const jsonRefs = require('json-refs');","symbol":"jsonRefs","correct":"import jsonRefs from 'json-refs';"},{"note":"The library exports a single default object containing all its methods, rather than named exports for individual functions.","wrong":"import { resolveRefs } from 'json-refs';","symbol":"resolveRefs","correct":"import jsonRefs from 'json-refs';\njsonRefs.resolveRefs(root, options);"},{"note":"All functions are properties of the default exported object. Direct destructuring from `require()` or named ESM imports are incorrect.","wrong":"const findRefs = require('json-refs').findRefs;","symbol":"findRefs","correct":"import jsonRefs from 'json-refs';\njsonRefs.findRefs(root, options);"}],"quickstart":{"code":"import jsonRefs from 'json-refs';\n\nconst documentWithRefs = {\n  a: 'Hello',\n  b: { $ref: '#/a' },\n  c: { $ref: 'external.json#/message' },\n  d: { $ref: 'https://example.com/api/spec.json#/paths/~1users' }\n};\n\nconst options = {\n  // For demonstration, mock a simple external file.\n  // In a real application, you'd use a loader for 'external.json'.\n  loaderOptions: {\n    processContent: function (res, callback) {\n      if (res.url.endsWith('external.json')) {\n        callback(null, {\n          text: JSON.stringify({ message: 'World from external!' })\n        });\n      } else {\n        callback(null, res.text);\n      }\n    }\n  },\n  // Important for resolving relative references like 'external.json'\n  location: 'file:///path/to/base/document.json' // Replace with actual base URI if needed\n};\n\njsonRefs.resolveRefs(documentWithRefs, options)\n  .then(function (res) {\n    console.log('Resolved Document:', JSON.stringify(res.resolved, null, 2));\n    console.log('Unresolved References:', res.unresolved);\n  })\n  .catch(function (err) {\n    console.error('Error resolving references:', err);\n  });","lang":"typescript","description":"Demonstrates how to resolve JSON References within a document, including local, relative, and external references."},"warnings":[{"fix":"Replace `options.relativeBase` with `options.location` in your configuration objects, providing the URI of the document being resolved.","message":"The `options.relativeBase` property has been removed. Users should now use `options.location` to specify the base URI for resolving relative references.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<2.1.7"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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';`.","cause":"Incorrect import statement for a CommonJS module in an environment expecting ESM, or attempting to destructure from the main export.","error":"TypeError: Cannot read properties of undefined (reading 'resolveRefs') OR TypeError: jsonRefs.resolveRefs is not a function"},{"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.","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.","error":"Error: Could not resolve reference: ... (followed by a path)"},{"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.","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.","error":"Circular reference detection (or lack thereof) leading to unexpected output or infinite loops."}],"ecosystem":"npm","meta_description":null}