Skip to content

Latest commit

 

History

History
208 lines (148 loc) · 8.57 KB

README.md

File metadata and controls

208 lines (148 loc) · 8.57 KB

JSON Schema Reader

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

npm License Buy us a tree

Build Status Coverage Status Dependencies

OS and Browser Compatibility

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

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 ❤

GitHub NPM Coveralls Travis CI SauceLabs