Validate JSON Files from the Shell with jsonlint-php

You will finish with a repeatable shell check for JSON syntax, a script-friendly exit-status test, and a small troubleshooting routine for the failures that jsonlint-php reports. The examples use jsonlint-php 1.10.2 from the Ubuntu package jsonlint version 1.10.2-1.

Allow about ten minutes. You need a shell, a readable JSON file, and the jsonlint package. The checks are ordinary, read-only operations. They do not edit the input, but take care with shell redirection because > can truncate an existing file.

1. Confirm the installed command

Check the executable and package before relying on its output. Neither command needs elevated privileges:

$ command -v jsonlint-php
/usr/bin/jsonlint-php
$ dpkg-query -W -f='${Package} ${Version}\n' jsonlint
jsonlint 1.10.2-1

The installed manual gives the command this shape: jsonlint-php file [options]. Its documented options are -q or --quiet and -h or --help. There is no documented --version option, so do not use one as a version check. The package query above is the reliable version check on this system.

2. Validate a known-good file

Create or choose a file whose contents are valid JSON. This example writes a new file in the current directory. Replace the filename with a safe destination that does not contain anything you need to keep:

$ printf '%s\n' '{"name":"Ada","active":true}' > valid.json
$ jsonlint-php valid.json
Valid JSON (valid.json)

A successful check prints Valid JSON followed by the filename and returns status 0. The command reads the file; it does not reformat or rewrite it.

$ printf 'exit status: %s\n' "$?"
exit status: 0

The status belongs to the command immediately before printf. If you run another command first, $? will describe that other command instead.

3. Use quiet mode in a script

Use --quiet when successful checks should produce no standard output. Branch on the exit status rather than parsing the words printed by normal mode:

if jsonlint-php --quiet valid.json; then
    printf '%s\n' 'JSON is valid'
else
    status=$?
    printf 'JSON check failed with status %s\n' "$status" &2
    exit "$status"
fi

For a valid file, the command itself prints nothing and the script prints JSON is valid. Quiet mode suppresses the success message; it does not suppress diagnostics for a bad file.

Do not use sudo just because a check failed. A permission error may require a deliberate access decision, but running a validator with elevated privileges can hide the fact that the account used by the real job cannot read the file. First check the path and permissions as the intended user.

4. Read a syntax error

JSON does not allow a trailing comma after the last object member. Test a separate file so the valid example remains available:

$ printf '%s\n' '{"name":"Ada",}' > invalid.json
$ jsonlint-php invalid.json
invalid.json: Parse error on line 1:
{"name":"Ada",}
-------------^
Expected: 'STRING' - It appears you have an extra trailing comma
$ printf 'exit status: %s\n' "$?"
exit status: 1

The caret points near the parser's failure and the final line gives a useful interpretation for this case. Output can include more context for other errors, but the non-zero status is the part a script should trust.

Another common failure is an unfinished object:

$ printf '%s\n' '{"name":"Ada"' > incomplete.json
$ jsonlint-php incomplete.json
incomplete.json: Parse error on line 1:
{"name":"Ada"
------------^
Expected one of: '}', ','

Repair the source file in its normal editor or generator. Do not overwrite the original with command output: jsonlint-php reports errors on standard output or standard error as appropriate, and it is not a formatter.

5. Separate missing files from bad JSON

A missing pathname also returns status 1, but its message is different:

$ jsonlint-php does-not-exist.json
File not found: does-not-exist.json
$ printf 'exit status: %s\n' "$?"
exit status: 1

That status means the check failed, not specifically that the JSON syntax was wrong. In a script, log the diagnostic and distinguish a missing or unreadable path from a parse error if the next action differs. Check spelling, the current directory, and access with ordinary read-only commands such as pwd and ls -l.

If a pipeline creates the file, verify that the producer completed before invoking the validator. A zero-byte or partially written file is a generation or ordering problem, not something jsonlint-php can repair.

6. Show the built-in usage text

Use --help when you need to check the locally installed interface:

$ jsonlint-php --help
Usage: /usr/bin/jsonlint-php file [options]

Options:
  -q, --quiet     Cause jsonlint to be quiet when no errors are found
  -h, --help      Show this message

This confirms the option names without relying on a different release's online documentation. Keep the filename as a separate shell argument and quote it when it contains whitespace:

$ jsonlint-php --quiet "$JSON_FILE"

For untrusted filenames, do not build an option string by concatenating user input. A pathname beginning with a hyphen can be interpreted as an option by many command-line tools. Resolve and review such paths before passing them to an automated check, and keep the command's documented argument order.