--- JSON-XS/XS.pm	2016/02/21 15:37:53	1.156
+++ JSON-XS/XS.pm	2016/02/26 21:46:45	1.157
@@ -103,7 +103,7 @@
 
 use common::sense;
 
-our $VERSION = 3.01;
+our $VERSION = 3.02;
 our @ISA = qw(Exporter);
 
 our @EXPORT = qw(encode_json decode_json);
@@ -1565,6 +1565,47 @@
 security right).
 
 
+=head1 "OLD" VS. "NEW" JSON (RFC 4627 VS. RFC 7159)
+
+TL;DR: Due to security concerns, JSON::XS will not allow scalar data in
+JSON texts by default - you need to create your own JSON::XS object and
+enable C<allow_nonref>:
+
+
+   my $json = JSON::XS->new->allow_nonref;
+
+   $text = $json->encode ($data);
+   $data = $json->decode ($text);
+
+The long version: JSON being an important and supposedly stable format,
+the IETF standardised it as RFC 4627 in 2006. Unfortunately, the inventor
+of JSON, Dougles Crockford, unilaterally changed the definition of JSON in
+javascript. Rather than create a fork, the IETF decided to standardise the
+new syntax (apparently, so Iw as told, without finding it very amusing).
+
+The biggest difference between thed original JSON and the new JSON is that
+the new JSON supports scalars (anything other than arrays and objects) at
+the toplevel of a JSON text. While this is strictly backwards compatible
+to older versions, it breaks a number of protocols that relied on sending
+JSON back-to-back, and is a minor security concern.
+
+For example, imagine you have two banks communicating, and on one side,
+trhe JSON coder gets upgraded. Two messages, such as C<10> and C<1000>
+might then be confused to mean C<101000>, something that couldn't happen
+in the original JSON, because niether of these messages would be valid
+JSON.
+
+If one side accepts these messages, then an upgrade in the coder on either
+side could result in this becoming exploitable.
+
+This module has always allowed these messages as an optional extension, by
+default disabled. The security concerns are the reason why the default is
+still disabled, but future versions might/will likely upgrade to the newer
+RFC as default format, so you are advised to check your implementation
+and/or override the default with C<< ->allow_nonref (0) >> to ensure that
+future versions are safe.
+
+
 =head1 INTEROPERABILITY WITH OTHER MODULES
 
 C<JSON::XS> uses the L<Types::Serialiser> module to provide boolean