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
• Debug unexpected schema validation results
• 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, our JSON Schema for OpenAPI video course, 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, and metaschema) | | JSON Schema Draft 2 | Partial (except validate, test, and metaschema) | | JSON Schema Draft 1 | Partial (except validate, test, and metaschema) | | JSON Schema Draft 0 | Partial (except validate, test, and metaschema) |

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 feature in detail. Additionally, running the JSON Schema CLI without passing a command will print convenient reference documentation:

• jsonschema version
• jsonschema validate
• jsonschema metaschema (ensure a schema is valid)
• jsonschema compile (for pre-compiling schemas)
• jsonschema test (write unit tests for your schemas)
• jsonschema fmt
• jsonschema lint
• jsonschema bundle (for inlining remote references in a schema)
• jsonschema inspect (for debugging references)
• jsonschema encode (for binary compression)
• jsonschema decode

See jsonschema.json for an experimental manifest for describing JSON Schema data models inspired by NPM's package.json.

Note that YAML is supported in most commands!

We also support a growing amount of pre-commit hooks. Take a look at the .pre-commit-hooks.yaml configuration file for what's available right now. Keep in mind that to use the pre-commit hooks, you need to install the CLI first.

If you are looking for more of a tutorial and overview of what the CLI is capable of, take a look at the Applying software engineering practices to JSON Schemas talk from the 2024 JSON Schema Conference. It covers advise on ontology design, linting, unit testing, CI/CD integration, and more:

Installation

The JSON Schema CLI is written using C++ and CMake, and supports macOS, Windows, and GNU/Linux.

From Homebrew

brew install sourcemeta/apps/jsonschema

From GitHub Actions

- uses: sourcemeta/[email protected]

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

- name: Checkout Repository
  uses: actions/checkout@v4

- name: Install the JSON Schema CLI
  uses: sourcemeta/[email protected]

# Then use as usual
- run: jsonschema fmt path/to/schemas --check

From npm

npm install --global @sourcemeta/jsonschema

From PyPI

pip install sourcemeta-jsonschema

From mise

mise use 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:

curl -fsSL https://raw.githubusercontent.com/sourcemeta/jsonschema/main/install -H 'Cache-Control: no-cache, no-store, must-revalidate' | /bin/sh

Keep in mind that it is hard to provide binaries that work across GNU/Linux distributions, given they often have major differences such as C runtimes (GLIC vs MUSL). We conservatively target Ubuntu 22.04, but you might need to build from source if your distribution of choice is different.

To verify the GPG signature of the checksums file:

curl --silent --show-error --location 'https://www.sourcemeta.com/gpg.asc' | gpg --import
gpg --verify CHECKSUMS.txt.asc CHECKSUMS.txt

From Dockerfile

Starting from v7.2.1, we publish a Docker image to GitHub Packages (amd64 and arm64), which you can use as follows:

docker run --interactive --volume "$PWD:/workspace" \
  ghcr.io/sourcemeta/jsonschema:vX.Y.Z lint --verbose myschema.json

Replace vX.Y.Z with your desired version. You can mount any directory as /workspace.

[!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.

From Snap

Starting from v10.0.0, we publish to the Snap store:

sudo snap install jsonschema

Keep in mind that due to Snap confinement requirements, the Snap is only able to access files under your $HOME directory.

With gah

If you are using gah:

gah install jsonschema

gah does not require sudo, but you need to have $HOME/.local/bin/ in your PATH.

Building from source

git clone https://github.com/sourcemeta/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 sourcemeta_jsonschema

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