diff --git a/reference/json/functions/json-decode.xml b/reference/json/functions/json-decode.xml
index c40b5d1a3d..8bcef3b195 100644
--- a/reference/json/functions/json-decode.xml
+++ b/reference/json/functions/json-decode.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.7 $ -->
+<!-- $Revision: 1.8 $ -->
 <refentry xml:id="function.json-decode" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>json_decode</refname>
@@ -100,6 +100,31 @@ $json = '{"foo-bar": 12345}';
 $obj = json_decode($json);
 print $obj->{'foo-bar'}; // 12345
 
+?>
+]]>
+    </programlisting>
+   </example>
+   <example>
+    <title>common mistakes using <function>json_decode</function></title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+
+// the following strings are valid JavaScript but not valid JSON
+
+// the name and value must be enclosed in double quotes
+// single quotes are not valid 
+$bad_json = "{ 'bar': 'baz' }";
+json_decode($bad_json); // null
+
+// the name must be enclosed in double quotes
+$bad_json = '{ bar: "baz" }';
+json_decode($bad_json); // null
+
+// trailing commas are not allowed
+$bad_json = '{ bar: "baz", }';
+json_decode($bad_json); // null
+
 ?>
 ]]>
     </programlisting>
@@ -109,6 +134,11 @@ print $obj->{'foo-bar'}; // 12345
 
  <refsect1 role="notes">
   &reftitle.notes;
+  <note>
+   <para>
+    The JSON spec is not JavaScript, but a subset of JavaScript.
+   </para>
+  </note>
   <caution>
    <para>
     This function will return false if the JSON encoded data is deeper than