Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

npm License Buy us a tree

Build Status Coverage Status Dependencies

OS and Browser Compatibility

This library provides core JSON Schema functionality and type definitions for APIDevTools projects.

NOTE: This is an internal library that is only intended to be used by other APIDevTools projects. Using it directly is discouraged and unsupported.


You can install via npm.

npm install @apidevtools/json-schema


When using this library in Node.js apps, you'll probably want to use CommonJS syntax:

const { JsonSchema } = require("@apidevtools/json-schema");

When using a transpiler such as Babel or TypeScript, or a bundler such as Webpack or Rollup, you can use ECMAScript modules syntax instead:

import { JsonSchema } from "@apidevtools/json-schema";

Populating a JSON Schema

To represent a JSON Schema, you'll need to create an instance of the JsonSchema class, which will contain one or more File objects.

const { JsonSchema, File } = require("@apidevtools/json-schema");

// This creates a JsonSchema object with one File object
let schema = new JsonSchema({
  url: "",
  data: {
    $schema: "",
    $id: "person",
    title: "Person",
    properties: {
      name: { $ref: "types.json#/$defs/Name" },
      address: { $ref: "types.json#address" }

// Add a second file to the schema
schema.files.push(new File({
  url: "",
  data: {
    $defs: {
      Name: {
        title: "Name",
        properties: {
          first: { type: "string" },
          last: { type: "string" }
      Address: {
        $anchor: "address",
        title: "Address",
        properties: {
          street: { type: "string" },
          city: { type: "string" },
          postalCode: { type: "string" }

Indexing the Schema

Once you have a JsonSchema object and all of its File objects, you can "index" the schema. That is, scan the schema's files and identify all the JSON Schema resources, anchors, and references in it.

// Index the schema that we created above πŸ‘†

// Now the schema's resources, anchors, and references are populated.
// Let's inspect the $refs in schema.json
let refs = [...schema.rootFile.references];

console.log(refs[0].locationInFile.path);   // /properties/name
console.log(refs[0].value);                 // types.json#/$defs/Name
console.log(refs[0].targetURI.href);        // /path/to/types.json#/$defs/Name

console.log(refs[1].locationInFile.path);   // /properties/address
console.log(refs[1].value);                 // types.json#address
console.log(refs[1].targetURI.href);        // /path/to/types.json#address

Note that indexing a schema can produce very different results, depending on the JSON Schema version. Calling schema.index() without any parameters will auto-detect the JSON Schema version via the $schema keyword. An error will be thrown if auto-detection fails.

An alternative is to explicitly specify the JSON Schema version when calling schema.index():

// Index the schema using Draft 4 rules

// Index the schema using Draft 2019-09 rules

Resolving References

Once the JsonSchema object has been indexed, $refs in the schema can be resolved. You can call the resolve() method on a Reference object:

// Call the resolve() method of the references we created above πŸ‘†

console.log(refs[0].resolve().data);    // { title: "Name", properties: {...}}

console.log(refs[1].resolve().data);    // { title: "Address", properties: {...}}

You can also use the JsonSchema.resolve() method to resolve arbitrary references within the schema:

// Resolving this reference entail traversing schema.json and types.json
let resolution = schema.resolve("");

// The Resolution object contains the final resolved value, as well as each resolution step along the way
console.log(;                         // { type: "string" }
console.log(resolution.locationInFile.path);          // /$defs/Name/properties/first
console.log(`${resolution.previousStep.reference}`);  // $ref:$defs/Name

Just like with the index() method, the behavior of the resolve() method depends on the JSON Schema version. By default, it will attempt to auto-detect the version, but you can explicitly specify it instead:

// Resolve a reference using Draft 4 rules

// Resolve a URI using Draft 2019-09 rules
schema.resolve("", "2019-09");

Browser support

This library supports recent versions of every major web browser. Older browsers may require Babel and/or polyfills.

To use in a browser, you'll need to use a bundling tool such as Webpack, Rollup, Parcel, or Browserify. Some bundlers may require a bit of configuration, such as setting browser: true in rollup-plugin-resolve.


Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.


To build the project locally on your computer:

  1. Clone this repo
    git clone

  2. Install dependencies
    npm install

  3. Build the code
    npm run build

  4. Run the tests
    npm test


This library is 100% free and open-source, under the MIT license. Use it however you want.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❀

GitHub NPM Coveralls Travis CI SauceLabs


Internal JSON Schema library used by APIDevTools







No releases published


No packages published