Usage#

The check-jsonschema CLI requires that you specify a JSON Schema and a set of instance files which are validated under that schema.

Typical usage is of the form

check-jsonschema --schemafile ./foo-schema.json foo-instance1.json foo-instance2.json

Detailed helptext is always available interactively via

check-jsonschema --help
Basic Options#

Option

Description

--schemafile

The path or URL for a file containing a schema to use.

-v, --verbose

Request more output.

-q, --quiet

Request less output.

-o [TEXT|JSON], --output-format [TEXT|JSON]

Use this option to choose how the output is presented. Either as TEXT (the default) or JSON, as in -o JSON.

--color [always|never|auto]

Control colorization of output. auto (the default) autodetects if the output is a terminal. always and never enable and disable colorization.

--traceback-mode [short|full]

By default, when an error is encountered, check-jsonschema will pretty-print the error and exit. Use --traceback-mode full to request the full traceback be printed, for debugging and troubleshooting.

Environment Variables#

The following environment variables are supported.

Environment Variables#

Name

Description

NO_COLOR

Set NO_COLOR=1 to explicitly turn off colorized output.

Schema Selection Options#

No matter what usage form is used, a schema must be specified.

There are several options for specifying schemas in different ways, in addition to --schemafile, but at least one of them must be used.

These options are mutually exclusive, so exactly one must be used.

Schema Options#

Option

Description

--schemafile

The path or URL for a file containing a schema to use.

--builtin-schema

The name of a builtin schema from check-jsonschema to use.

--check-metaschema

Validate each instancefile as a JSON Schema, using the relevant metaschema defined in "$schema".

--builtin-schema Choices#

The following values are valid and refer to vendored copies schemas from SchemaStore and other sources:

  • vendor.azure-pipelines

  • vendor.bamboo-spec

  • vendor.bitbucket-pipelines

  • vendor.buildkite

  • vendor.cloudbuild

  • vendor.dependabot

  • vendor.drone-ci

  • vendor.github-actions

  • vendor.github-workflows

  • vendor.gitlab-ci

  • vendor.readthedocs

  • vendor.renovate

  • vendor.travis

  • vendor.woodpecker-ci

The following values refer to custom schemas:

  • github-workflows-require-timeout – This schema checks that a GitHub workflow explicitly sets timeout-minutes on all jobs. (The default value for this is 6 hours.)

Downloading and Caching#

By default, when --schemafile is used to refer to an http:// or https:// location, the schema is downloaded and cached based on the schema’s Last-Modified time. The following options control caching behaviors.

Caching Options#

Option

Description

--no-cache

Disable caching.

--cache-filename

The name to use for caching a remote schema. Defaults to using the last slash-delimited part of the URI.

“format” Validation Options#

JSON Schema defines a "format" attribute for string fields but does not require that any validation for formats be applied.

check-jsonschema supports checking several "format"s by default. The following options can be used to control this behavior.

--disable-formats#

Disable specified "format" checks.

Use --disable-formats "*" to disable all format checking.

Because "format" checking is not done by all JSON Schema tools, it is possible that a file may validate under a schema with a different tool, but fail with check-jsonschema if --disable-formats is not set.

This option may be specified multiple times or as a comma-delimited list and supports the following formats as arguments:

  • date

  • date-time

  • duration

  • email

  • hostname

  • idn-email

  • idn-hostname

  • ipv4

  • ipv6

  • iri

  • iri-reference

  • json-pointer

  • regex

  • relative-json-pointer

  • time

  • uri

  • uri-reference

  • uri-template

  • uuid

Example usage:

# disables all three of time, date-time, and iri
--disable-formats time,date-time --disable-formats iri

--format-regex#

Set a mode for handling of the "regex" value for "format". The modes are as follows:

Regex Options#

mode

description

default

Require the regex to be valid in ECMAScript regex syntax.

python

Require the regex to be valid in Python regex syntax.

Other Options#

--default-filetype#

The default filetype to assume on instance files when they are detected neither as JSON nor as YAML.

For example, pass --default-filetype yaml to instruct that files which have no extension should be treated as YAML.

By default, this is not set and files without a detected type of JSON or YAML will fail.

--data-transform#

--data-transform applies a transformation to instancefiles before they are checked. The following transforms are supported:

  • azure-pipelines:

    “Unpack” compile-time expressions for Azure Pipelines files, skipping them for the purposes of validation. This transformation is based on Microsoft’s lanaguage-server for VSCode and how it handles expressions

  • gitlab-ci:

    Handle !reference tags in YAML data for gitlab-ci files. This transform has no effect if the data is not being loaded from YAML, and it does not interpret !reference usages – it only expands them to lists of strings to pass schema validation

--fill-defaults#

JSON Schema specifies the "default" keyword as potentially meaningful for consumers of schemas, but not for validators. Therefore, the default behavior for check-jsonschema is to ignore "default".

--fill-defaults changes this behavior, filling in "default" values whenever they are encountered prior to validation.

Warning

There are many schemas which make the meaning of "default" unclear. In particular, the behavior of check-jsonschema is undefined when multiple defaults are specified via anyOf, oneOf, or other forms of polymorphism.

--base-uri#

check-jsonschema defaults to using the "$id" of the schema as the base URI for $ref resolution, falling back to the retrieval URI if "$id" is not set.

--base-uri overrides this behavior, setting a custom base URI for $ref resolution.

--validator-class#

check-jsonschema allows users to pass a custom validator class which implements the jsonschema.protocols.Validator protocol.

The format used for this argument is <module>:<class>. For example, to explicitly use the jsonschema validator for Draft7, use --validator-class 'jsonschema.validators:Draft7Validator'.

The module containing the validator class must be importable from within the check-jsonschema runtime context.

Note

check-jsonschema will treat the validator class similarly to the jsonschema library builtin validators. This includes using documented extension points like passing a format checker or the behavior enabled with --fill-defaults. Users of this feature are recommended to build their validators using jsonschema’s documented interfaces (e.g. jsonschema.validators.extend) to ensure that their validators are compatible.