json-refs

What is json-refs?

The json-refs npm package is a utility for working with JSON references, which are pointers within JSON objects that reference other parts of the JSON document. It helps resolve these references and can be used to make JSON documents easier to understand and manipulate by consolidating linked data.

What are json-refs's main functionalities?

Resolving JSON References

This feature allows the resolution of JSON references within a JSON document. The code sample demonstrates how to resolve references in a JSON file located at a specified path, with an option to resolve circular references.

{
  "jsonRefs": require('json-refs'),
  "path": './somePath/to/json',
  "options": { resolveCirculars: true },
  "resolvedJson": function() {
    var root = jsonRefs.resolveRefsAt(this.path, this.options).then(function (results) {
      console.log(results.resolved);
    }).catch(function (err) {
      console.error(err.stack);
    });
    return root;
  }
}

Finding JSON References

This feature involves identifying all the JSON references in a given JSON object. The code sample shows how to find all references, including those that might be invalid, within a JSON object.

{
  "jsonRefs": require('json-refs'),
  "jsonObject": { /* some JSON object */ },
  "options": { includeInvalid: true },
  "foundRefs": function() {
    var refs = jsonRefs.findRefs(this.jsonObject, this.options);
    console.log(refs);
    return refs;
  }
}

Other packages similar to json-refs

swagger-parser

Swagger Parser is a package that can parse, validate, and dereference Swagger and OpenAPI documents. Similar to json-refs, it handles resolving references but is specifically tailored for Swagger and OpenAPI specs, providing more specialized functionality in these contexts compared to the more general-purpose json-refs.

json-schema-ref-parser

This package dereferences JSON Schema $refs pointers. Like json-refs, it resolves references within JSON documents but focuses specifically on JSON Schema, making it ideal for scenarios involving JSON Schema validation and manipulation.

README

json-refs

Various utilities for JSON References, and JSON Pointers since JSON References are part JSON Pointer.

Project Badges

• Build status:
• Dependencies:
• Developer dependencies:
• Downloads:
• License:
• Version:

Installation

json-refs is available for both Node.js and the browser. Installation instructions for each environment are below.

Browser

Installation for browser applications can be done via Bower or by downloading a standalone binary.

Using Bower

bower install json-refs --save

Standalone Binaries

The standalone binaries come in two flavors:

• json-refs-standalone.js: 692kb, full source and source maps
• json-refs-standalone-min.js: 48kb, minified, compressed and no sourcemap

Node.js

Installation for Node.js applications can be done via [NPM][npm].

npm install json-refs --save

APIs

All examples below use a variable called jsonRefs. Here is how to create it in Node.js:

var jsRefs = require('json-refs');

For the browser, JsonRefs is exported.

findRefs (json)

Arguments

• json {object} - The JavaScript object to search for references

Response

An object whose keys are JSON Pointers to where the JSON Reference's $ref node is and the JSON Reference string.

isJsonReference (obj)

Arguments

• [obj] {*} - The object to check

Response

true if the argument is an object and its $ref property is a JSON Pointer and false otherwise.

isRemotePointer (ptr)

Arguments

• ptr {*} - The JSON Pointer to check

Response

true if the argument is an is a JSON Pointer to a remote document and false otherwise.

pathFromPointer (ptr)

Arguments

• ptr {string} - A JSON Pointer string

Response

A string[] of path segments for the JSON Pointer unless its a remote reference in which case ptr is returned as-is.

Example

console.log(jsonRefs.pathFromPointer('#/owner/login')); // ['owner', 'login']

pathToPointer (path)

Arguments

• path {string[]} - An array of path segments.

Response

A string representing a JSON Pointer.

Example

console.log(jsonRefs.pathToPointer(['owner', 'login'])); // #/owner/login

resolveRefs (json, options, done)

Arguments

• json {object}: The JavaScript object containing zero or more JSON References
• [options] {object}: The options
• [options.prepareRequest] {function}: The callback used to prepare a request
• [options.processContent] {function}: The callback used to process the remote request content
• done {function}: An error-first callback to be called with the fully-resolved object and metadata for the reference resolution

Response

If there is an Error, the callback is called with the Error in the first argument and undefined in the second argument. If there is no Error, the first argument is undefined and the second argument is an object whose value is the fully resolved document. The third argument is an object whose value is the reference resolution metadata. Its keys are the location of the reference and it's values are as follows:

• ref {string}: The reference value as it existed in the original document
• [value] {*}: The resolved value of the reference, if there is one. If this property was set, this means that the reference was resolvable and it resolved to an explicit value. If this property is not set, that means the reference was unresolvable. A value of undefined means that the reference was resolvable to an actual value of undefined and is not indicative of an unresolvable reference.
• `

##Usage

Note: If you need to alter your request in any way, for example to add specific headers to the request or to add authentication to the request or any other situation in which the request might need to be altered, you will need to use the options.prepareRequest callback. Here is a simple example that uses options.prepareRequest to make a secure request using an Basic Authentication (The example is written for Node.js but the actual business logic in how resolveRefs is called sould be the same in the browser):

var jsonRefs = require('json-refs');
var json = {
  name: 'json-refs',
  owner: {
    $ref: 'https://api.github.com/repos/whitlockjc/json-refs#/owner'
  }
};
jsonRefs.resolveRefs(json, {
  prepareRequest: function (req) {
    // Add the 'Basic Authentication' credentials
    req.auth('whitlockjc', 'MY_GITHUB_PASSWORD');

    // Add the 'X-API-Key' header for an API Key based authentication
    // req.set('X-API-Key', 'MY_API_KEY');
  }
}, function (err, rJson, metadata) {
  if (err) throw err;

  console.log(JSON.stringify(rJson)); // {name: 'json-refs', owner: {/* GitHub Repository Owner Information */}}
  console.log(JSON.stringify(metadata)); // {'#/owner/$ref': {ref: 'https://api.github.com/repos/whitlockjc/json-refs#/owner', value: {/*GitHub Repository Onwer Information */}}}
});

Note: If you need to pre-process the content of your remote requets, like to support data not explicitly supported by Superagent, you can use the options.processContent callback. Here is a simple example that uses options.processContent to retrieve a YAML resource:

var jsonRefs = require('json-resf');
var YAML = require('yamljs');

jsonRefs.resolveRefs({
  $ref: 'http://somehost/somefile.yaml'
}, {
  processContent: function (content) {
    return YAML.parse(content);
  }
}, function (err, rJson, metadata) {
  if (err) throw err;

  console.log(JSON.stringify(rJson)); // Document should be JSON equivalent of your YAML document
});

###Node.js

var jsonRefs = require('json-refs');
var json = {
  name: 'json-refs',
  owner: {
    $ref: 'https://api.github.com/repos/whitlockjc/json-refs#/owner'
  }
};
jsonRefs.resolveRefs(json, function (err, rJson, metadata) {
  if (err) throw err;

  console.log(JSON.stringify(rJson)); // {name: 'json-refs', owner: {/* GitHub Repository Owner Information */}}
  console.log(JSON.stringify(metadata)); // {'#/owner/$ref': {ref: 'https://api.github.com/repos/whitlockjc/json-refs#/owner', value: {/*GitHub Repository Onwer Information */}}}
});

###Browser

Bower

<html>
  <head>
    <title>Bower Example</title>
    <script src="bower_components/lodash/lodash.js"></script>
    <script src="bower_components/superagent/superagent.js"></script>
    <script src="bower_components/traverse/traverse.js"></script>
    <script src="bower_components/json-refs/browser/json-refs.js"></script>
  </head>
  <body>
  </body>
  <script>
    var json = {
      name: 'json-refs',
      owner: {
        $ref: 'https://api.github.com/repos/whitlockjc/json-refs#/owner'
      }
    };

    JsonRefs.resolveRefs(json, function (err, rJson) {
      if (err) throw err;

      console.log(rJson);
    });
  </script>
</html>

Standalone

<html>
  <head>
    <title>Standalone Example</title>
    <script src="json-refs-standalone.js"></script>
  </head>
  <body>

  </body>
  <script>
    var json = {
      name: 'json-refs',
      owner: {
        $ref: 'https://api.github.com/repos/whitlockjc/json-refs#/owner'
      }
    };

    JsonRefs.resolveRefs(json, function (err, rJson) {
      if (err) throw err;

      console.log(rJson);
    });
  </script>
</html>