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

Features

• Performant. Hot paths are memoized, only one crawl is needed, and remote authorities are resolved concurrently.
• 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.

Usage

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

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

// fs in node.. in general this library works just fine in the browser though
const fs = require('fs');

// readers can do anything, so long as they have a read function that returns a promise that resolves to a value
const httpReader = {
  async read(ref) {
    return request(ref.toString());
  },
};

// this would obviously only be possible in node
const fileReader {
  async read(ref) {
    return fs.read(ref.toString(true));
  },
};

const source = {
  definitions: {
    someOASFile: {
      $ref: './main.oas2.yml#/definitions/user',
    },
    someMarkdownFile: {
      $ref: 'https://foo.com/intro.md',
    },
  },
};

// set our resolver, passing in our scheme -> reader mapping
const resolver = new Resolver({
  readers: {
    http: httpReader,
    https: httpReader,
    file: fileReader,
  },
});

const resolved = await resolver.resolve(source);

console.log(resolved.result);
// {
//   definitions: {
//     someOASFile: // .. whatever data is in the file located in the location definitions.foo in file './main.oas2.yml#/definitions/user'
//     someMarkdownFile: // .. whatever data is returned from https://foo.com/intro.md
//   },
// }