@stoplight/json-ref-resolver

What is @stoplight/json-ref-resolver?

@stoplight/json-ref-resolver is a utility for resolving JSON references ($ref) in JSON documents. It helps in dereferencing and bundling JSON schemas or other JSON documents that contain references to other documents or internal references.

What are @stoplight/json-ref-resolver's main functionalities?

Dereferencing JSON References

This feature allows you to resolve internal JSON references within a document. The example shows how a reference to '#/bar' is resolved to the actual content of 'bar'.

const { resolve } = require('@stoplight/json-ref-resolver');

const document = {
  "foo": { "$ref": "#/bar" },
  "bar": { "baz": 123 }
};

resolve(document).then(result => {
  console.log(result);
  // Output: { foo: { baz: 123 }, bar: { baz: 123 } }
});

Resolving External JSON References

This feature allows you to resolve external JSON references by fetching the referenced document from a URL. The example shows how a reference to an external URL is resolved.

const { resolve } = require('@stoplight/json-ref-resolver');

const document = {
  "foo": { "$ref": "http://example.com/bar.json" }
};

resolve(document).then(result => {
  console.log(result);
  // Output will depend on the content of http://example.com/bar.json
});

Custom Resolvers

This feature allows you to define custom resolvers for handling specific types of references. The example shows how to create a custom resolver for a 'custom://' scheme.

const { resolve } = require('@stoplight/json-ref-resolver');

const customResolver = {
  canRead: (file) => file.url.startsWith('custom://'),
  read: (file) => Promise.resolve({ custom: 'data' })
};

const document = {
  "foo": { "$ref": "custom://example" }
};

resolve(document, { resolvers: [customResolver] }).then(result => {
  console.log(result);
  // Output: { foo: { custom: 'data' } }
});

Other packages similar to @stoplight/json-ref-resolver

json-schema-ref-parser

json-schema-ref-parser is a powerful library for parsing, resolving, and dereferencing JSON Schema $ref pointers. It supports both internal and external references and provides similar functionality to @stoplight/json-ref-resolver. However, it is more focused on JSON Schema specifically.

json-ref-lite

json-ref-lite is a lightweight library for resolving JSON references. It is simpler and has fewer features compared to @stoplight/json-ref-resolver, making it suitable for basic use cases where performance and simplicity are priorities.

json-refs

json-refs is another library for resolving JSON references. It provides a comprehensive set of features for both internal and external references, similar to @stoplight/json-ref-resolver. It also includes additional utilities for working with JSON references.

README

JSON Ref Resolver

Recursively resolves JSON pointers and remote authorities.

• Explore the interfaces: TSDoc
• View the changelog: Releases

Features

• Performant. Hot paths are memoized, remote authorities are resolved concurrently, and the minimum surface area is crawled and resolved.
• Caching. Results from remote authorities are cached.
• Immutable. The original object is not changed, and structural sharing is used to only change relevant bits.
• Reference equality. Pointers to the same location will resolve to the same object in memory.
• Flexible. Bring your own readers for http://, file://, mongo://, custom://... etc.
• Reliable. Well tested to handle all sorts of circular reference edge cases.

Installation

Supported in modern browsers and node.

# latest stable
yarn add @stoplight/json-ref-resolver

Usage

All relevant types and options can be found in src/types.ts.

import { Resolver } from '@stoplight/json-ref-resolver';

// some example http library
const request = require('request');

// if we're in node, we create a file reader with fs
const fs = require('fs');

// create our resolver instance
const resolver = new Resolver({
  // readers can do anything, so long as they define an async read function that resolves to a value
  readers: {
    // this reader will be invoked for refs with the https protocol
    https: {
      async read(ref: uri.URI) {
        return request(ref.toString());
      },
    },

    // this reader will be invoked for refs with the file protocol
    file: {
      async read(ref: uri.URI) {
        return fs.read(ref.toString());
      },
    },
  },
});

const resolved = await resolver.resolve({
  definitions: {
    someOASFile: {
      $ref: './main.oas2.yml#/definitions/user',
    },
    someMarkdownFile: {
      $ref: 'https://foo.com/intro.md',
    },
  },
});

console.log(resolved.result);

// ==> outputs the original object, with refs resolved and replaced
//
// {
//   definitions: {
//     someOASFile: {
//       // ... the data located in the relative file `./main.oas2.yml` and inner json path `#/definitions/user`
//     },
//     someMarkdownFile: {
//       // ... the data located at the url `https://foo.com/intro.md`
//     }
//   },
// }