@sourcemeta/jsonschema
Version:
The CLI for working with JSON Schema. Covers formatting, linting, testing, and much more for both local development and CI/CD pipelines. By a member of the JSON Schema Technical Steering Committee
296 lines (222 loc) • 12.4 kB
Markdown
[](https://github.com/sourcemeta/jsonschema/releases)
[](https://www.npmjs.com/package/@sourcemeta/jsonschema)
[](https://www.npmjs.com/package/@sourcemeta/jsonschema)
[](https://pypi.org/project/sourcemeta-jsonschema)
[](https://github.com/sourcemeta/jsonschema/actions)
[](https://github.com/sourcemeta/jsonschema/graphs/contributors/)
[](https://github.com/sourcemeta/jsonschema/blob/main/.pre-commit-hooks.yaml)
[](https://doi.org/10.5281/zenodo.20086212)
[](https://snapcraft.io/jsonschema)
The command-line tool for working with [JSON Schema](https://json-schema.org),
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**](#usage)
Pairs with [Sourcemeta One](https://www.sourcemeta.com) for a complete schema
registry workflow.
***
> [!TIP]
> Do you want to level up your JSON Schema skills? Check out
> [learnjsonschema.com](https://www.learnjsonschema.com), our growing JSON
> Schema documentation website, our [JSON Schema for
> OpenAPI](https://www.sourcemeta.com/courses/jsonschema-for-openapi) video
> course, and our O'Reilly book [Unifying Business, Data, and Code: Designing
> Data Products with JSON
> Schema](https://www.oreilly.com/library/view/unifying-business-data/9781098144999/).
***
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 `codegen`) |
| JSON Schema Draft 2 | Partial (except `validate`, `test`, `metaschema`, `upgrade`, `codegen`, and `lint`) |
| JSON Schema Draft 1 | Partial (except `validate`, `test`, `metaschema`, `upgrade`, `codegen`, and `lint`) |
| JSON Schema Draft 0 | Partial (except `validate`, `test`, `metaschema`, `upgrade`, `codegen`, and `lint`) |
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](https://github.com/alombarte), co-founder of the
[KrakenD](https://www.krakend.io) API Gateway.
> Huge shout out to this tool. Our governance pipeline uses it to produce
> better analysis of the examples in our OpenAPI documents. While Spectral does
> some basic validation of examples, the diagnostics from this tool are far
> superior.
[@DavidBiesack](https://github.com/DavidBiesack), Chief API Officer at
[Apiture](https://www.apiture.com).
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`](./docs/version.markdown)
- [`jsonschema validate`](./docs/validate.markdown)
- [`jsonschema metaschema`](./docs/metaschema.markdown) (ensure a schema is valid)
- [`jsonschema compile`](./docs/compile.markdown) (for pre-compiling schemas)
- [`jsonschema test`](./docs/test.markdown) (write unit tests for your schemas)
- [`jsonschema fmt`](./docs/format.markdown)
- [`jsonschema lint`](./docs/lint.markdown)
- [`jsonschema bundle`](./docs/bundle.markdown) (for inlining remote references in a schema)
- [`jsonschema upgrade`](./docs/upgrade.markdown) (for upgrading schemas to a newer JSON Schema dialect)
- [`jsonschema inspect`](./docs/inspect.markdown) (for debugging references)
- [`jsonschema rdf`](./docs/rdf.markdown) (for turning instances into Linked Data / JSON-LD)
- [`jsonschema codegen`](./docs/codegen.markdown) (for generating code from schemas)
- [`jsonschema encode`](./docs/encode.markdown) (for binary compression)
- [`jsonschema decode`](./docs/decode.markdown)
- [`jsonschema install`](./docs/install.markdown) (for fetching external schema dependencies)
> See [`jsonschema.json`](./docs/configuration.markdown) for an _experimental_
manifest for describing JSON Schema data models inspired by NPM's
`package.json`, including dependency management.
Note that YAML is supported in most commands!
We also support a growing amount of [`pre-commit`](https://pre-commit.com)
hooks. Take a look at the
[`.pre-commit-hooks.yaml`](https://github.com/sourcemeta/jsonschema/blob/main/.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](https://www.youtube.com/watch?v=wJ7bK22n3IU) talk from the 2024 [JSON
Schema Conference](https://conference.json-schema.org). It covers advise on
ontology design, linting, unit testing, CI/CD integration, and more:
[](https://www.youtube.com/watch?v=wJ7bK22n3IU)
Going Further
-------------
The JSON Schema CLI handles the local development and CI/CD side of schema
management. For teams that need to publish, discover, and govern schemas across
an organisation, [Sourcemeta One](https://www.sourcemeta.com) is a self-hosted
JSON Schema registry that pairs directly with this CLI. It is designed by the
same team, requires no database, deploys as a single Docker container, and is
free to deploy.
Installation
------------
The JSON Schema CLI is written using C++ and [CMake](https://cmake.org/), and
supports macOS, Windows, and GNU/Linux.
### From Homebrew
```sh
brew install sourcemeta/apps/jsonschema
```
### From GitHub Actions
```yaml
- uses: sourcemeta/jsonschema@vX.Y.Z
```
Where `X.Y.Z` is replaced with the desired version. For example:
```yaml
- name: Checkout Repository
uses: actions/checkout@v4
- name: Install the JSON Schema CLI
uses: sourcemeta/jsonschema@v16.3.0
# Then use as usual
- run: jsonschema fmt path/to/schemas --check
```
### From npm
```sh
npm install --global @sourcemeta/jsonschema
```
### From PyPI
```sh
pip install sourcemeta-jsonschema
```
### From mise
```sh
mise use jsonschema
```
### From GitHub Releases
We publish precompiled binaries for every supported platform to [GitHub
Releases](https://github.com/sourcemeta/jsonschema/releases), including a
[continuous](https://github.com/sourcemeta/jsonschema/releases/tag/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:
```sh
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. We conservatively target Ubuntu and Alpine, but you might need
to build from source if your distribution of choice is different.
> [!NOTE]
> On GNU/Linux (and other non-macOS, non-Windows platforms), the CLI performs
> HTTP requests through your system's cURL library, which it loads at runtime.
> This keeps the binaries distribution-independent and makes them respect your
> system's TLS trust store. `libcurl` is present on most systems, but if it is
> missing you can install it through your package manager (for example
> `apt install libcurl4`, `dnf install libcurl`, or `apk add libcurl`). If it
> lives in a non-standard location, point the CLI at it by setting the
> `SOURCEMETA_CORE_CURL_SO` environment variable to the full path of
> `libcurl.so.4`.
To verify the GPG signature of the checksums file:
```sh
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](https://github.com/sourcemeta/jsonschema/pkgs/container/jsonschema)
(`amd64` and `arm64`), which you can use as follows:
```sh
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:
```sh
sudo snap install jsonschema
```
Keep in mind that due to [Snap
confinement](https://snapcraft.io/docs/snap-confinement) requirements, the Snap
is only able to access files under your `$HOME` directory.
### With gah
If you are using [gah](https://github.com/marverix/gah):
```sh
gah install jsonschema
```
gah does not require sudo, but you need to have `$HOME/.local/bin/` in your `PATH`.
### Building from source
```sh
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`.
For performance reasons, the build will take as much advantage of your specific
machine capabilities. If you desire to build a portable binary, or if the
aggressive processor-specific optimisations cause any issues (we heard of some
`Illegal instruction` cases), then configure the project with
`-DJSONSCHEMA_PORTABLE:BOOL=ON`.
License
-------
This project is released under the terms of the [GNU Affero General Public
License v3.0](./LICENSE).
**A note for enterprises:** Using the JSON Schema CLI as a tool during local
development or as part of your CI/CD pipelines does not trigger the AGPL
copyleft requirements. Your schemas, data, and surrounding code remain entirely
yours. This is the same way that managing your proprietary code with
[Git](https://git-scm.com) does not make your code subject to the
[GPL](https://www.gnu.org/licenses/gpl-3.0.en.html). For any other use, please
refer to the full [license](./LICENSE).