Warning! If you are making use of this package on NPM, be aware that its location will moved to @sourcemeta/jsonschema on the next version. Please upgrade your package.json accordingly.

The command-line tool for working with JSON Schema, the world most popular schema language. It is a comprehensive solution for maintaining repositories of schemas and ensuring their quality, both during local development and when running on CI/CD pipelines. For example:

• Ensure your schemas are valid
• Unit test your schemas against valid and invalid instances
• Enforce consistent indentation and keyword ordering in your schema files
• Detect and fix common JSON Schema anti-patterns
• Inline external references for conveniently distributing your schemas

Check out the documentation to learn more

[!TIP] Do you want to level up your JSON Schema skills? Check out learnjsonschema.com, our growing JSON Schema documentation website, and our O'Reilly book Unifying Business, Data, and Code: Designing Data Products with JSON Schema.

Version support

We aim to fully support every version of JSON Schema and combinations between them.

| Dialect | Support | |---------------------|------------------------------------------------------------------| | JSON Schema 2020-12 | Full | | JSON Schema 2019-09 | Full | | JSON Schema Draft 7 | Full | | JSON Schema Draft 6 | Full | | JSON Schema Draft 4 | Full | | JSON Schema Draft 3 | Partial (except validate, test, metaschema, and compile) | | JSON Schema Draft 2 | Partial (except validate, test, metaschema, and compile) | | JSON Schema Draft 1 | Partial (except validate, test, metaschema, and compile) | | JSON Schema Draft 0 | Partial (except validate, test, metaschema, and compile) |

What our users are saying

Amazing product. Very useful for formatting and bundling my schemas, plus it surfaced various referencing issues. 10 out of 10!

@alombarte, co-founder of the KrakenD API Gateway.

Usage

The functionality provided by the JSON Schema CLI is divided into commands. The following pages describe each command in detail. Additionally, running the JSON Schema CLI without passing a command will print convenient reference documentation:

• jsonschema validate
• jsonschema metaschema (ensure a schema is valid)
• jsonschema test (write unit tests for your schemas)
• jsonschema fmt
• jsonschema lint
• jsonschema bundle (for inlining remote references in a schema)
• jsonschema frame (for debugging references)
• jsonschema compile (for internal debugging)
• jsonschema identify

Installation

The JSON Schema CLI is written using C++ and CMake, and supports macOS, Windows, and GNU/Linux. Under the hood, it relies on the powerful JSON Toolkit library.

From Homebrew

brew install intelligence-ai/apps/jsonschema

From GitHub Actions

- uses: intelligence-ai/[email protected]

Where X.Y.Z is replaced with the desired version. For example:

- uses: intelligence-ai/[email protected]
# Then use as usual
- run: jsonschema fmt path/to/schemas --check

From NPM

npm install --global @intelligence-ai/jsonschema

From GitHub Releases

We publish precompiled binaries for every supported platform to GitHub Releases, including a continuous that is updated on every commit from the main branch.

For convenience, we also provide a POSIX shell script capable of installing the latest pre-built binaries, which you can run as follows:

/bin/sh -c "$(curl -fsSL https://raw.githubusercontent.com/intelligence-ai/jsonschema/main/install -H "Cache-Control: no-cache, no-store, must-revalidate")"

From Dockerfile

You can compile the JSON Schema CLI inside a container and run it with Docker as follows:

docker build -t jsonschema .

Then, you run the JSON Schema CLI by mounting the desired directory as /workspace as follows:

docker run --interactive --volume "$PWD:/workspace" jsonschema lint --verbose myschema.json

# You can optionally add this to your .alias (or similar) file:
# alias jsonschema="docker run --interactive --volume \"$PWD:/workspace\" jsonschema"

[!WARNING] Make sure to NOT allocate a pseudo-TTY when running the CLI through Docker (i.e. the --tty/-t option) as it might result in line ending incompatibilities between the container and host, which will affect formatting. Plus a TTY is not required for running a tool like the JSON Schema CLI.

Building from source

git clone https://github.com/intelligence-ai/jsonschema
cd jsonschema
cmake -S . -B ./build -DCMAKE_BUILD_TYPE:STRING=Release
cmake --build ./build --config Release --parallel 4
cmake --install ./build --prefix <prefix> \
  --config Release --verbose --component intelligence_jsonschema

Where <prefix> can be any destination prefix of your choosing, such as /opt or /usr/local.

Coming Soon

This project is under heavy development, and we have a lot of cool things in the oven. In the mean-time, star the project to show your support!

| Feature | Description | Status | |-----------------------|------------------------------------------------------------------------------------|-------------| | Debugging | Validate a JSON instance against a JSON Schema step by step, like LLDB and GDB | Not started | | Upgrading/Downgrading | Convert a JSON Schema into a later or older dialect | Not started |

License

This project is governed by the AGPL-3.0 copyleft license.