test.markdown

Testing

Warning

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

jsonschema test [schemas-or-directories...]
  [--http/-h] [--verbose/-v] [--resolve/-r <schemas-or-directories> ...]
  [--extension/-e <extension>] [--ignore/-i <schemas-or-directories>]

Schemas are code. As such, you should run an automated unit testing suite against them. Just like popular test frameworks like Jest, GoogleTest, and PyTest, the JSON Schema CLI provides a schema-oriented test runner inspired by the official JSON Schema test suite.

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

Examples

To create a test definition, you must write JSON documents that look like this:

{
  "target": "http://json-schema.org/draft-04/schema#",
  "$comment": "An arbitrary comment! Put whatever you want here",
  "tests": [
    {
      "description": "The empty object is valid",
      "valid": true,
      "data": {}
    },
    {
      "description": "The `type` keyword must be a string",
      "valid": false,
      "data": {
        "type": 1
      }
    },
    {
      "description": "Load from an external file, relative to the test",
      "valid": true,
      "dataPath": "../my-data.json"
    }
  ]
}

Tip

You can test different portions of a large schema by passing a schema URI that contains a JSON Pointer in the target property. For example: https://example.com/my-big-schema#/definitions/foo.

Assuming this file is saved as test/draft4.json, you can run it as follows:

jsonschema test test/draft4.json

Run a single test definition

jsonschema test path/to/test.json

Run every .json test definition in a given directory (recursively)

jsonschema test path/to/tests/

Run every .json test definition in the current directory (recursively)

jsonschema test

Run every .json test definition in the current directory while ignoring another

jsonschema test --ignore dist

Run every .test.json test definition in the current directory (recursively)

jsonschema test --extension .test.json

Run a single test definition enabling HTTP resolution

jsonschema test path/to/test.json --http

Run a single test definition importing a single local schema

jsonschema test path/to/test.json --resolve path/to/external.json

Run a single test definition importing a directory of .schema.json schemas

jsonschema test path/to/test.json --resolve path/to/schemas --extension schema.json