<!-- doc/src/sgml/json.sgml -->

<sect1 id="datatype-json">
 <title><acronym>JSON</acronym> Types</title>

 <indexterm zone="datatype-json">
  <primary>JSON</primary>
 </indexterm>

 <indexterm zone="datatype-json">
  <primary>JSONB</primary>
 </indexterm>

 <para>
  JSON data types are for storing JSON (JavaScript Object Notation)
  data, as specified in <ulink url="https://datatracker.ietf.org/doc/html/rfc7159">RFC
  7159</ulink>. Such data can also be stored as <type>text</type>, but
  the JSON data types have the advantage of enforcing that each
  stored value is valid according to the JSON rules.  There are also
  assorted JSON-specific functions and operators available for data stored
  in these data types; see <xref linkend="functions-json"/>.
 </para>

 <para>
  <productname>PostgreSQL</productname> offers two types for storing JSON
  data: <type>json</type> and <type>jsonb</type>. To implement efficient query
  mechanisms for these data types, <productname>PostgreSQL</productname>
  also provides the <type>jsonpath</type> data type described in
  <xref linkend="datatype-jsonpath"/>.
 </para>

 <para>
  The <type>json</type> and <type>jsonb</type> data types
  accept <emphasis>almost</emphasis> identical sets of values as
  input.  The major practical difference is one of efficiency.  The
  <type>json</type> data type stores an exact copy of the input text,
  which processing functions must reparse on each execution; while
  <type>jsonb</type> data is stored in a decomposed binary format that
  makes it slightly slower to input due to added conversion
  overhead, but significantly faster to process, since no reparsing
  is needed.  <type>jsonb</type> also supports indexing, which can be a
  significant advantage.
 </para>

 <para>
  Because the <type>json</type> type stores an exact copy of the input text, it
  will preserve semantically-insignificant white space between tokens, as
  well as the order of keys within JSON objects. Also, if a JSON object
  within the value contains the same key more than once, all the key/value
  pairs are kept.  (The processing functions consider the last value as the
  operative one.)  By contrast, <type>jsonb</type> does not preserve white
  space, does not preserve the order of object keys, and does not keep
  duplicate object keys.  If duplicate keys are specified in the input,
  only the last value is kept.
 </para>

 <para>
  In general, most applications should prefer to store JSON data as
  <type>jsonb</type>, unless there are quite specialized needs, such as
  legacy assumptions about ordering of object keys.
 </para>

 <para>
  <acronym>RFC</acronym> 7159 specifies that JSON strings should be encoded in UTF8.
  It is therefore not possible for the JSON
  types to conform rigidly to the JSON specification unless the database
  encoding is UTF8. Attempts to directly include characters that
  cannot be represented in the database encoding will fail; conversely,
  characters that can be represented in the database encoding but not
  in UTF8 will be allowed.
 </para>

 <para>
  <acronym>RFC</acronym> 7159 permits JSON strings to contain Unicode escape sequences
  denoted by <literal>\u<replaceable>XXXX</replaceable></literal>.  In the input
  function for the <type>json</type> type, Unicode escapes are allowed
  regardless of the database encoding, and are checked only for syntactic
  correctness (that is, that four hex digits follow <literal>\u</literal>).
  However, the input function for <type>jsonb</type> is stricter: it disallows
  Unicode escapes for characters that cannot be represented in the database
  encoding.  The <type>jsonb</type> type also
  rejects <literal>\u0000</literal> (because that cannot be represented in
  <productname>PostgreSQL</productname>'s <type>text</type> type), and it insists
  that any use of Unicode surrogate pairs to designate characters outside
  the Unicode Basic Multilingual Plane be correct.  Valid Unicode escapes
  are converted to the equivalent