Validate JSON against a schema with validate-json

By the end of this guide, you will have checked a JSON document against a JSON Schema, understood the useful exit statuses, and separated invalid data from a broken command invocation. The examples target the installed validate-json 5.2.13 command from Debian's php-json-schema package.

Allow about 10 minutes. You need a shell, readable JSON files, and a schema in JSON Schema Draft 4 format. Validation is read-only: it does not edit either file and does not require sudo. The command is useful in a shell script, but treat its non-zero status as a real failure before allowing generated or user-supplied data onwards.

1. Check the installed command

Start by confirming which executable will run and which package supplied it. This avoids debugging a different copy earlier in your PATH:

$ command -v validate-json
/usr/bin/validate-json
$ dpkg-query -W -f='${Package} ${Version}\n' php-json-schema
php-json-schema 5.2.13-1

The manpage describes two input forms: validate-json data.json and validate-json data.json schema.json. The first form only works when the data contains a $schema property that identifies a schema the validator can resolve.

2. Create a small explicit schema

Put the document and schema in a working directory. These examples use a temporary path so the test does not alter an application directory:

$ workdir=$(mktemp -d /tmp/validate-json-example.XXXXXX)
$ printf '%s\n' '{"name":"Ada","age":36}' > "$workdir/data.json"
$ printf '%s\n' '{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"age":{"type":"integer"}}}' > "$workdir/schema.json"
$ cat "$workdir/schema.json"
{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"age":{"type":"integer"}}}

In a real project, keep the schema under version control beside the code that consumes the data. A schema is a contract, so review changes to required properties and types as carefully as code changes.

There is no persistent state to undo here. When you finish testing, remove only the temporary directory you created, after checking its path:

$ printf 'temporary directory: %s\n' "$workdir"
$ rm -rf -- "$workdir"

3. Validate with an explicit schema

Pass the JSON document first and the schema second:

$ validate-json "$workdir/data.json" "$workdir/schema.json"
$ printf 'exit status: %s\n' "$?"
exit status: 0

No output means success in the normal mode. Status 0 is the result to test in automation. If you want a human-readable success line, add --verbose:

$ validate-json --verbose "$workdir/data.json" "$workdir/schema.json"
OK. The supplied JSON validates against the schema.

--quiet suppresses normal output while keeping the status useful:

$ validate-json --quiet "$workdir/data.json" "$workdir/schema.json"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Use ordinary user privileges. The command only needs read access to the two files and any schema resources it resolves.

4. Make a failure useful

Change the document so a required property is missing and a typed property has the wrong JSON type:

$ printf '%s\n' '{"age":"thirty"}' > "$workdir/bad.json"
$ validate-json "$workdir/bad.json" "$workdir/schema.json"
JSON does not validate. Violations:
[name] The property name is required
[age] String value found, but an integer is required
$ printf 'exit status: %s\n' "$?"
exit status: 23

Status 23 means the document was read but did not satisfy the schema. The bracketed path identifies the property involved. Fix the producer or the schema; do not silence the result merely to keep a pipeline green.

Malformed JSON is a different problem:

$ printf '{bad\n' > "$workdir/malformed.json"
$ validate-json "$workdir/malformed.json" "$workdir/schema.json"
Error loading JSON data file
JSON parse error: JSON_ERROR_SYNTAX
$ printf 'exit status: %s\n' "$?"
exit status: 5

A missing or unreadable data file returns status 3. Check the path, ownership, permissions, and whether a producer finished writing the file before you invoke the validator. Do not grant wider permissions as the first response.

5. Use schema autodetection when the document carries it

An input document can identify its schema with $schema. For a local smoke test, use the Draft 4 schema URL and keep the schema rules in the document itself:

$ printf '%s\n' '{"$schema":"http://json-schema.org/draft-04/schema#","type":"object","properties":{"name":{"type":"string"}}}' > "$workdir/self-described.json"
$ validate-json --verbose "$workdir/self-described.json"
OK. The supplied JSON validates against the schema.

Autodetection is not a fallback for a document without that property. With no explicit schema and no usable $schema, the command reports that the data must be an object with a $schema property and exits with status 6. Prefer the explicit two-file form when the schema is maintained separately or when repeatable deployment matters.

6. Inspect the bundled Draft 4 reference

The manpage lists --dump-schema and --dump-schema-url. In this installed version, they are used with a data-file argument:

$ validate-json "$workdir/data.json" --dump-schema-url
http://json-schema.org/draft-04/schema#
$ validate-json "$workdir/data.json" --dump-schema | head -n 4
{
    "id": "http:\/\/json-schema.org\/draft-04\/schema",
    "$schema": "http:\/\/json-schema.org\/draft-04\/schema#",
    "description": "Core schema meta-schema"

The dump is a diagnostic reference for the validator's bundled meta-schema, not a substitute for your application's schema. If a flag unexpectedly prints help, compare the argument order with the installed command and manpage rather than assuming that an empty output means success.