Perl's JSON Handling Capabilities

Which Module Should You Use?

• JSON: Best default when you want a stable interface for encode_json, decode_json, and the object API without committing your code to one backend.
• JSON::PP: Good when you need pure Perl, a dependency that ships with modern Perl, or explicit control over features like core_bools.
• JSON::XS: A direct XS choice for hot paths that encode or decode large payloads frequently.
• JSON::MaybeXS: Useful in app code that wants an XS backend when available and a pure-Perl fallback otherwise.

The current JSON module checks PERL_JSON_BACKEND first. If you do not set it, the documented fallback order is JSON::XS, then JSON::PP, then JSON::backportPP. That makes backend selection predictable if you configure it deliberately, and surprising if you never do.

Encoding Perl Data to JSON

Encoding is straightforward when you pass hashrefs or arrayrefs and use explicit JSON booleans rather than Perl strings like "false".

Practical Example

#!/usr/bin/perl
use strict;
use warnings;
use JSON qw(encode_json);

my $payload = {
    user_id   => 101,
    name      => "Alice",
    active    => JSON::true,
    deleted   => JSON::false,
    tags      => ["perl", "json"],
    last_login => undef,
};

my $json = encode_json($payload);

print $json, "\n";

In encoded output, undef becomes null. If you need stable key ordering for snapshot tests or diffs, use the object interface and enable canonical. Pretty printing improves readability, but it does not sort keys by itself.

my $json = JSON->new
    ->canonical(1)
    ->pretty(1)
    ->encode($payload);

Decoding JSON Back Into Perl

Decoding turns JSON objects into hashrefs and arrays into arrayrefs. The main footgun is booleans: decoded JSON booleans are not the same thing as the literal Perl strings "true" and "false".

Safer Decode Example

#!/usr/bin/perl
use strict;
use warnings;
use JSON::PP qw(is_bool);

my $decoder = JSON::PP->new->core_bools;
my $data;

eval {
    $data = $decoder->decode('{"ok":true,"roles":["admin","editor"]}');
};

if ($@) {
    die "Invalid JSON: $@";
}

print $data->{roles}[0], "\n";
print $data->{ok} ? "enabled\n" : "disabled\n";
print is_bool($data->{ok}) ? "boolean\n" : "not boolean\n";

With JSON::PP, the core_bools option can return Perl core booleans on modern Perl instead of backend-specific boolean objects. That is useful when you want fewer surprises moving values through the rest of your application.

Options That Matter in Real Code

• canonical: Produces stable key ordering, which is valuable for tests, caching keys, and deterministic output.
• pretty: Makes output readable for logs, examples, and config files.
• allow_nonref: Lets you encode or decode top-level scalar JSON values. Set it explicitly if your code depends on this behavior across environments.
• convert_blessed: Calls an object's TO_JSON method during encoding.
• allow_blessed: Keeps encoding from dying on blessed values that you are willing to collapse to null.
• relaxed: Helpful for internal config formats, but avoid it for public API input because it accepts non-standard JSON.

Blessed Object Example

package User;

sub new {
    my ($class, $id, $name) = @_;
    bless { id => $id, name => $name }, $class;
}

sub TO_JSON {
    my ($self) = @_;
    return { id => $self->{id}, name => $self->{name} };
}

package main;
use JSON;

my $user = User->new(7, "Mina");
my $json = JSON->new->convert_blessed->encode($user);

Performance and Deployment Consistency

XS backends remain materially faster for heavy JSON workloads, but performance is only half the story. Consistency matters too. If one environment uses JSON::XS and another silently falls back to JSON::PP, edge behavior around booleans, blessed values, or defaults can show up in tests and logs.

When that matters, pin the backend explicitly with PERL_JSON_BACKEND or depend on the backend you want directly. A common pattern is to keep general application code on the JSON API while forcing backend choice in CI and production so output is repeatable.

PERL_JSON_BACKEND=JSON::XS

# or, if you want an ordered fallback chain:
PERL_JSON_BACKEND=Cpanel::JSON::XS,JSON::XS,JSON::PP

Common Mistakes and Troubleshooting

• Encoding "false" or "true" as strings when your API actually expects JSON booleans.
• Assuming hash order is stable without enabling canonical.
• Passing non-standard JSON from logs or hand-edited config files into strict decoders and then treating the parser error as a Perl bug.
• Forgetting that unknown blessed objects throw during encoding unless you opt into convert_blessed or allow_blessed.

When a payload is failing to decode, formatting and validating the JSON first is often faster than stepping through Perl line by line. Clean structure makes backend-specific errors much easier to interpret.

Bottom Line

Perl's JSON support is mature and flexible. The main choice is not whether Perl can handle JSON, but how explicit you want to be about backend selection, boolean behavior, and object serialization. Start with JSON for the common API, move to JSON::PP when you want core-only portability, and use XS when throughput is part of the requirement rather than a guess.