Skip to content

validate.markdown

Latest commit

 

History

History
199 lines (151 loc) · 6.47 KB

validate.markdown

File metadata and controls

199 lines (151 loc) · 6.47 KB

Validating

Warning

JSON Schema Draft 3 and older are not supported at this point in time.

jsonschema validate <schema.json|.yaml> <instance.json|.jsonl|.yaml|directory...>
  [--http/-h] [--verbose/-v] [--debug/-g]
  [--resolve/-r <schemas-or-directories> ...]
  [--benchmark/-b] [--loop <iterations>] [--extension/-e <extension>]
  [--ignore/-i <schemas-or-directories>] [--trace/-t] [--fast/-f]
  [--template/-m <template.json>] [--json/-j] [--entrypoint/-p <pointer|uri>]

The most popular use case of JSON Schema is to validate JSON documents. The JSON Schema CLI offers a validate command to evaluate one or many JSON instances, directories of instances, or JSONL datasets against a JSON Schema, presenting human-friendly information on unsuccessful validation.

The --json/-j option outputs the evaluation result using the JSON Schema Flag or Basic standard format depending on whether the --fast/-f option is set.

If you want to validate that a schema adheres to its metaschema, use the metaschema command instead.

To help scripts distinguish validation errors, these are reported using exit code 2.

Note

Annotations are only printed when passing the --verbose/-v or the --trace/-t options. However, annotation collection will be skipped if the --fast/-f option is passed.

Warning

By default, schemas are validated in exhaustive mode, which results in better error messages, at the expense of speed. The --fast/-f option makes the schema compiler optimise for speed, at the expense of error messages.

To speed-up the compilation process, you may pre-compile a schema using the compile command and pass the result using the --template/-m option. However, you still need to pass the original schema for error reporting purposes. Make sure they match and that the compilation and evaluation were done with the same version of this tool or you might get non-sense results.

Tip

Templates produced by the compile command can also be evaluated from JavaScript using the Blaze JavaScript port, a pure-JavaScript evaluator for browsers and JavaScript runtimes like Node.js, letting you compile with this CLI and validate anywhere.

Warning

This tool (and its underlying Blaze evaluator) does not support turning on format validation in JSON Schema 2019-09 and older (an optional feature as per the specification), nor the optional JSON Schema 2020-12 format-assertion vocabulary (which has seen extremely little adoption in the wild). Over time, format optional validation proved to be inconsistent across implementations and led to significant confusion in the community. We strongly suggest you treat format as an annotation and explicitly validate strings with the less ambiguous pattern keyword, if needed.

Examples

For example, consider the following JSON Schema Draft 4 schema that asserts that the JSON instance is a string:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "string"
}

Also consider a JSON instance called instance.json that looks like this:

12345

This instance is an integer, while the given schema expects a string. Validating the instance against the schema using the JSON Schema CLI will result in the following output:

$ jsonschema validate schema.json instance.json
error: The target document is expected to be of the given type
    at instance location ""
    at evaluate path "/type"

Validate a JSON instance against a schema

jsonschema validate path/to/my/schema.json path/to/my/instance.json

Validate a JSON instance against a schema and print the result as JSON

jsonschema validate path/to/my/schema.json path/to/my/instance.json --json

Validate a JSON instance against a schema with a pre-compiled template

jsonschema compile path/to/my/schema.json > template.json
jsonschema validate path/to/my/schema.json path/to/my/instance.json \
  --template template.json

Validate a JSON instance against a schema in fast mode

jsonschema validate path/to/my/schema.json path/to/my/instance.json --fast

Validate a multiple JSON instances against a schema

jsonschema validate path/to/my/schema.json \
  path/to/my/instance_1.json \
  path/to/my/instance_2.json \
  path/to/my/instance_3.json

Validate a JSONL dataset against a schema

jsonschema validate path/to/my/schema.json path/to/my/dataset.jsonl

Validate a JSON instance enabling HTTP resolution

jsonschema validate path/to/my/schema.json path/to/my/instance.json --http

Validate a JSON instance importing a single local schema

jsonschema validate path/to/my/schema.json path/to/my/instance.json \
  --resolve path/to/external.json

Validate a JSON instance importing a directory of .schema.json schemas

jsonschema validate path/to/my/schema.json path/to/my/instance.json \
  --resolve path/to/schemas --extension schema.json

Validate a JSON instance against a schema printing timing information

jsonschema validate path/to/my/schema.json path/to/my/instance.json --benchmark

Validate a JSON instance against a schema with trace information

jsonschema validate path/to/my/schema.json path/to/my/instance.json --trace

Validate a directory of instances against a schema

jsonschema validate path/to/my/schema.json path/to/instances/

Validate a directory of instances with a specific extension

jsonschema validate path/to/my/schema.json path/to/instances/ --extension .data.json

Validate a directory of instances while ignoring certain paths

jsonschema validate path/to/my/schema.json path/to/instances/ \
  --ignore path/to/instances/drafts

Validate a JSON instance against a specific subschema

jsonschema validate path/to/my/schema.json path/to/my/instance.json \
  --entrypoint '/$defs/MyType'