README.md

JSON Schema Reader

Reads multi-file JSON Schemas from files, URLs, and other sources

Features

• 🔱 Read files from anywhere
  Reads JSON Schemas from local files, network files, and web URLs by default. Can be extended to read from a database, FTP server, CMS, or anything else!

• 🗃 Multi-file schemas
  Split your schemas into as many files as you want, and use $ref to link between them.

• 📃 Broad compatibility
  Supports multiple versions of the JSON Schema spec, including the latest 2019-09 draft, and can even auto-detect the correct version.

• 🏷Supports any file type
  Supports JSON, plain-text, and binary files by default, but can be extended to support YAML, TOML, XML, or any other file type.

• 🧩 Fully customizable
  Allows you to extend/override any part of the process. Add support for additional file locations, file types, syntaxes, schema versions, etc.

• 🧪 Thoroughly tested
  Tested on over 1,500 real-world schemas from Google, Microsoft, Facebook, Spotify, etc.

Example

This example demonstrates reading a multi-file JSON Schema. The root file (schema.json) contains two $refs that link to address.json. One of the $refs use a JSON Pointer path (#/$defs/Name), and the other a named anchor (#address).

schema.json

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "Person",
  "properties": {
    "name": { "$ref": "types.json#/$defs/Name" },
    "address": { "$ref": "types.json#address" }
  }
}

types.json

{
  "$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" }
      }
    }
  }
}

script.js

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

(async () => {
  // Read the schema, and all referenced files
  let schema = await readJsonSchema("schema.json");

  // List all the files in the schema
  console.log(schema.files.length);           // 2
  console.log(schema.rootFile.path);          // schema.json
  console.log(schema.files[1].path);          // types.json

  // 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[0].resolve().data);        // { title: "Name", properties: {...}}

  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
  console.log(refs[1].resolve().data);        // { title: "Address", properties: {...}}
})();

Installation

You can install JSON Schema Reader via npm.

npm install @apidevtools/json-schema-reader

Usage

When using JSON Schema Reader in Node.js apps, you'll probably want to use CommonJS syntax:

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

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 { readJsonSchema } from "@apidevtools/json-schema-reader";

readJsonSchema(location, [options])

This is an async function that reads your JSON Schema from a file path or URL. If the schema contains any $refs to other files and/or URLs, then they are automatically read/downloaded as well.

location (string or URL object)

This is the location of the root file of your JSON Schema. When running in Node.js, it can be an absolute or relative filesystem path, or a URL. When running in a web browser, it can be an absolute or relative URL.

options (optional, Options object)

You can pass an Options object as the second parameter to customize the behavior of the readJsonSchema() function.

Return value (JsonSchema object)

This is an async function, so the return value is a Promise, but the Promise resolves to a JsonSchema object, which contains details about all the files, resources, anchors, and references in the schema.

Documentation

• Understanding the structure of a schema
  • JsonSchema
  • File
  • Resource
  • Anchor
  • Reference
  • Pointer
• Options / Customization
• Reading files from other sources
• Supporting other file types
• Error handling

Browser support

JSON Schema Reader supports recent versions of every major web browser. Older browsers may require Babel and/or polyfills.

To use JSON Schema Reader 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.

Contributing

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

Building

To build the project locally on your computer:

1. Clone this repo
   git clone https://github.com/APIDevTools/json-schema-reader.git

2. Install dependencies
   npm install

3. Build the code
   npm run build

4. Run the tests
   npm test

License

JSON Schema Reader 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 ❤