Validate JSON Against a Schema with validate-json

A pipeline that ships broken JSON downstream has only hidden the bug, and validate-json's exit statuses are how you catch it before that happens. This guide checks a document against a JSON Schema, separates invalid data from a broken invocation, and covers the command's non-zero statuses one by one. Examples target the installed validate-json 5.2.13 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 edits neither file and does not need sudo. It is useful inside a shell script, but treat its non-zero status as a real failure before letting generated or user-supplied data continue 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.

• --verbose adds a human-readable success line.
• --quiet suppresses normal output while keeping the status useful.

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

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

Use ordinary user privileges throughout. 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 own 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 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 empty output means success.