++ed by:

5 PAUSE user(s)
2 non-PAUSE user(s).

David J. Oswald


JSON::Tiny - Minimalistic JSON. No dependencies.


  use JSON::Tiny qw(decode_json encode_json);

  # Encode and decode JSON (die on errors)
  my $bytes = encode_json({foo => [1, 2], bar => 'hello!', baz => \1});
  my $hash  = decode_json($bytes);

  # Handle errors
  my $json = JSON::Tiny->new;
  my $err  = $json->error;
  say $err ? "Error: $err" : $hash->{message};


JSON::Tiny is a minimalistic standalone adaptation of Mojo::JSON, from the Mojolicious framework. It is a single-source-file module with 315 lines of code and core-only dependencies.

Features include transparent Unicode support, speed, small memory footprint, and a minimal code base ideal for bundling or inlining. Along with Mojo:JSON, it is possibly the fastest pure-Perl implementation of RFC 7159.

JSON::Tiny supports normal Perl data types like scalar, array reference, hash reference, and will try to call the TO_JSON method on blessed references, or stringify them if it doesn't exist.

Differentiating between strings and numbers in Perl is hard; depending on how it has been used, a scalar can be both at the same time. The string value gets precedence unless both representations are equivalent.



  true  -> JSON::Tiny->true
  false -> JSON::Tiny->false
  null  -> undef

In addition scalar references will be used to generate Booleans, based on if their values are true or false.

  \1 => true
  \0 => false



JSON::Tiny implements the following functions, which can be imported individually.


  my $value = decode_json($bytes);

Decode JSON to Perl value and die if decoding fails.


  my $bytes = encode_json({foo => 'bar'});

Encode Perl value to JSON.


  my $value = j($bytes);

Encode Perl data structure (which may only be an array reference or hash reference) or decode JSON. Dies if decoding fails.


JSON::Tiny implements the following attributes.


  my $err = $json->error;

Parser errors.


JSON::Tiny implements the following methods.


  my $json = JSON::Tiny->new;

Instantiate a JSON::Tiny object.


  my $value  = $json->decode($bytes);

Decode JSON to Perl value and set "error" if decoding failed.



Encode Perl value to JSON.


  my $false = JSON::Tiny->false;
  my $false = $json->false;

False value, used because Perl has no native equivalent.


  my $true = JSON::Tiny->true;
  my $true = $json->true;

True value, used because Perl has no native equivalent.

More on Booleans




As an advanced option, users requiring a plain old literal 0 or 1, may set $JSON::Tiny::FALSE = 0; and $JSON::Tiny::TRUE = 1;. Any value, including blessed references will work. The setting must be made prior to calling a JSON decoding method or function. Use local to constrain the scope of the change.


JSON::Tiny compared with JSON::PP from the JSON distribution:

  • JSON::PP is configurable, but more complex. JSON::Tiny offers sane defaults, and no configuration.

  • Download and install with cpanm: JSON::PP, 5.2 seconds. JSON::Tiny, 1.9 seconds.


  • Simple Design: JSON has 2254 lines of code, six modules and five files. Distribution: 85KB.

    JSON::Tiny has 315 lines of code; an embeddable single-file module. Distribution: 19KB.

  • JSON::PP has 42 functions and methods. JSON::Tiny has nine.

  • Performance Benchmarks:

                 Rate   JSON_PP JSON_Tiny
      JSON_PP   304/s        --      -52%
      JSON_Tiny 636/s      109%        --

    JSON uses JSON::XS if it's available, in which case JSON wins. See examples/json_bench.pl for benchmark code.

    JSON::Tiny's lightweight design reduces its startup time as compared to the JSON module. This is beneficial to frequently run applications like CGI.

  • Light Memory Needs: Memory usage was tested with http://valgrind.org/valgrind and Devel::MemoryTrace::Light by running examples/json_pp.pl and examples/json_tiny.pl.

                 valgrind  Devel::MemoryTrace::Light
      JSON::PP   5.1MB     3.7MB
      JSON::Tiny 4.5MB     2.6MB


No configuration.


Perl 5.8.1 or newer. However, Perl 5.10 is the recommended minimum due to bugs in Perl 5.8's regular expression engine.


Incompatible with Exporter versions predating Perl 5.8.4. For older Perl versions upgrade Exporter to version 5.59 or newer.


David Oswald, <davido at cpan.org>

Code and tests were adapted from Mojo::JSON.



You can find documentation for this module with the perldoc command.

  perldoc JSON::Tiny

You may look for additional information at:


The Mojolicious team for their excellent product that offers a lightweight JSON implementation. This module was adapted from Mojo::JSON, chosen as a model because it is robust, minimal, and well tested. Mojo::JSON's tests were also adapted to a dependency-free design.

Christian Hansen, whos GitHub Gist provided the basis for Mojo::JSON, and subsequently JSON::Tiny.

Randal Schwartz showed his pure-regexp JSON parser (PerlMonks) to Los Angeles Perl Mongers (Sept 2012). He wasn't involved in JSON::Tiny, but my exploration of alternatives to his solution led to this fork of Mojo::JSON.


Copyright 2012-2014 David Oswald.


See http://www.perlfoundation.org/artistic_license_2_0 for more information.


Mojo::JSON, JSON, RFC7159.

Hosting generously
sponsored by Bytemark