Use json_pp to Inspect, Canonicalise and Convert JSON Safely

You will finish with a repeatable way to format JSON, produce stable key ordering for comparisons, and convert JSON into Perl's Data::Dumper form. The examples target json_pp 4.16 from Perl 5.38.2, installed here by the perl package.

Allow about ten minutes. You need a shell and readable input. No command in this guide needs elevated privileges. The utility reads standard input and writes standard output, so it does not modify an input file unless you explicitly redirect output over it.

1. Check the installed command

Confirm which executable your shell will run, then record its version. These are ordinary, read-only checks:

$ command -v json_pp
/usr/bin/json_pp
$ json_pp -V
4.16
$ dpkg-query -W -f='${Package} ${Version}\n' perl
perl 5.38.2-3.2ubuntu0.6

The exact package revision is host-specific. The -V output is the useful compatibility marker for the utility itself. If another Perl installation appears first in PATH, read its documentation before relying on this guide's version-specific observations.

2. Pretty-print JSON without changing the source

The default input format is JSON and the default output is pretty-printed JSON. Pass a small document through a pipe when you want a quick check:

$ printf '%s\n' '{"z":2,"a":[true,null,"cafe"]}' | json_pp
{
   "a" : [
      true,
      null,
      "cafe"
   ],
   "z" : 2
}

Whitespace has been added and the keys are shown in a different order on this installed version. That is presentation, not a change to the JSON values. The command's output is standard output, which makes it useful for inspecting a file without rewriting it:

$ json_pp < input.json > formatted.json
$ test -s formatted.json && echo 'formatted output exists'
formatted output exists

Do not use > input.json while reading that same file. The shell truncates the destination before json_pp can read it, which can destroy the source. Write a new file, inspect it, and replace the original only after you have made an explicit backup.

3. Make output stable for diffs

Use the canonical JSON::PP option when you want object keys ordered consistently. Add utf8 when the output should contain UTF-8 characters rather than escaped byte sequences:

$ printf '%s\n' '{"z":2,"a":[true,null,"cafe"]}' | json_pp -json_opt canonical,utf8
{"a":[true,null,"cafe"],"z":2}

Canonical output is compact on this installation. It is useful for review files and repeatable comparisons, but it is not a cryptographic signature and does not make untrusted data trustworthy. If people need to read the result, use pretty as well:

$ printf '%s\n' '{"z":2,"a":[true,null,"cafe"]}' | json_pp -json_opt pretty,canonical,utf8
{
   "a" : [
      true,
      null,
      "cafe"
   ],
   "z" : 2
}

Options for JSON::PP are supplied as one comma-separated argument. This is valid: -json_opt pretty,canonical. Repeating the option as -json_opt pretty -json_opt canonical is not the documented form.

4. Convert JSON to Perl's Data::Dumper format

Set the input format explicitly with -f json and the output format with -t dumper. This is handy when debugging a Perl data structure or checking how JSON numbers and strings are represented:

$ printf '%s\n' '{"name":"Ada","values":[1,2]}' \
    | json_pp -f json -t dumper
{
  name => "Ada",
  values => [
    1,
    2
  ]
}

The formatting of Data::Dumper output is for inspection, not a promise of JSON syntax. Do not feed this result to a JSON parser. To convert it back, use a deliberate Perl-evaluation step only when the source is trusted and controlled.

5. Treat -f eval as code execution

The manual permits Perl code as an input format:

$ printf '%s\n' '{foo => 7, bar => [1,2]}' \
    | json_pp -f eval -t dumper
{
  bar => [
    1,
    2
  ],
  foo => 7
}

This is not a relaxed JSON parser. It evaluates Perl syntax. Never use -f eval on a download, an upload, a log entry, or any other data an untrusted person can influence. A malicious value can run Perl code with the privileges of the process. If the input is supposed to be JSON, leave the input format as the default or specify -f json.

There is no persistent change to undo in this example, but a harmful evaluated input may already have changed the system before the command exits. If you have evaluated untrusted content, stop using that environment, preserve relevant evidence, and follow your incident-response process.

6. Handle parse failures without trusting partial output

Invalid JSON causes a non-zero exit status and a diagnostic on standard error. Capture the streams separately when a script needs to decide whether conversion succeeded:

$ printf '%s\n' '{bad}' > /tmp/example.json
$ json_pp < /tmp/example.json > /tmp/example.formatted.json 2> /tmp/example.error
$ printf 'status: %s\n' "$?"
status: 255
$ sed -n '1p' /tmp/example.error
unexpected end of string while parsing JSON string, at character offset 2 (before "ad}\x{a}") at /usr/bin/json_pp line 59.

Error wording and the reported line can vary with the Perl build. The reliable checks are the non-zero status and the presence of a diagnostic. Treat the output file as unusable after a failed conversion, even if it exists or contains some text. Keep the original input until the replacement has passed your own checks.

For a successful conversion, test the status immediately and then validate the resulting file with the next tool in your workflow. A successful json_pp run proves that the input was accepted and converted; it does not prove that the data has the schema your application expects.

7. Keep the lesser-used switches in context

The -t null output format performs no output action. It can be useful only when another part of a wrapper cares about parsing and exit status. It is not a validation report and it will not print the converted document.

The -v option currently has no action in this version. Do not use it as a promise of verbose diagnostics. If you need to investigate a failure, capture standard error and preserve the command's exit status instead.

Options such as relaxed, allow_singlequote, allow_barekey and loose make accepted input less strict. Do not add them to make malformed data disappear. First establish whether the producer is meant to emit JSON, then fix or reject the producer's output. A successful parse under relaxed rules may still be rejected by another JSON implementation.