From d5b2590685af21ce7ec9cfff132df481bef85e3e Mon Sep 17 00:00:00 2001 From: Zsolt Parragi Date: Mon, 20 Jul 2026 10:47:22 +0000 Subject: [PATCH v2 8/8] Add json5 type documentation Describe the json5 type in the JSON types chapter: the accepted JSON5 syntax, the encoding caveat for non-ASCII characters outside strings, verbatim storage, and the cast paths to and from json and jsonb. Also list the type in the data type overview table. --- doc/src/sgml/datatype.sgml | 6 ++ doc/src/sgml/json.sgml | 134 ++++++++++++++++++++++++++++++++++++- 2 files changed, 139 insertions(+), 1 deletion(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index 89985ab7b16..c1cb7bc587b 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -145,6 +145,12 @@ textual JSON data + + json5 + + textual JSON5 data + + jsonb diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml index 8a2aad5935e..f462d985396 100644 --- a/doc/src/sgml/json.sgml +++ b/doc/src/sgml/json.sgml @@ -26,7 +26,9 @@ data: json and jsonb. To implement efficient query mechanisms for these data types, PostgreSQL also provides the jsonpath data type described in - . + . In addition, the + json5 type described in + accepts data written in the extended JSON5 syntax. @@ -234,6 +236,136 @@ SELECT '{"reading": 1.230e-5}'::json, '{"reading": 1.230e-5}'::jsonb; + + The <type>json5</type> Type + + + JSON5 + + + + The json5 type stores data written in + JSON5, an extension of JSON + with a more permissive syntax that is intended to be easier to + write and maintain by hand. Since JSON5 is a superset of JSON, + every valid json value is also a valid + json5 value. In addition to standard JSON, the + following constructs are accepted: + + + + + Single-line (//) and block + (/* */) comments. + + + + + Additional whitespace: vertical tab, form feed, the byte order + mark (U+FEFF), all Unicode space separators such as the no-break + space (U+00A0), and the line terminators U+2028 and U+2029. + These also end a single-line comment. + + + + + A single trailing comma after the last element of an array or + the last member of an object. + + + + + Unquoted object keys, for keys that are valid ECMAScript 5.1 + identifier names, e.g., {key: "value"}. Such + keys start with a Unicode letter, $ or + _, and can continue with those, digits, + combining marks and connector punctuation. Characters can also + be written as \uXXXX + escapes. The words true, + false, null, + Infinity and NaN can also be + used as unquoted keys. Identifiers are not accepted in place of + values. + + + + + Single-quoted strings, e.g., 'value'. + + + + + Additional string escapes: \', + \v, \0 and + \xHH. A backslash + followed by any other character that is not a digit stands for + that character, e.g., \q is + q. Control characters other than line breaks + need not be escaped inside strings. + + + + + Strings continued across multiple lines by escaping the line + break with a backslash; the escaped line break is not part of + the string value. The line break can be LF, CR, CR LF, U+2028 or + U+2029. + + + + + Extended number formats: hexadecimal integers + (0xFF), a leading or trailing decimal point + (.5, 5.), an explicit + plus sign (+5), and the special values + Infinity and NaN, + optionally preceded by a sign. + + + + + + + Non-ASCII characters outside of strings, that is Unicode whitespace + and non-ASCII characters in unquoted keys, are only recognized when + the database encoding is UTF8. With other + encodings, non-ASCII characters in unquoted keys have to be written + as \u escapes. + + + + Like json, the json5 type stores an exact + copy of the validated input text, so comments and formatting are + preserved. There are no functions or operators that process + json5 values directly; instead, a json5 + value can be cast to json or jsonb + (both are assignment casts). These casts convert the value to + standard JSON: comments and trailing commas are removed, object + keys and strings are written in double-quoted form, and numbers + written in one of the extended formats are rewritten in standard + form, e.g., .5 becomes 0.5 + and 0xFF becomes 255. The values Infinity, + -Infinity and NaN have no + equivalent in standard JSON, so casting a json5 value + containing them raises an error. Like jsonb, the + conversion to json can't represent the character + \u0000 (also written \0 or + \x00) unless the input is valid standard JSON, + which is cast unchanged. Functions that build JSON from SQL values, + such as to_json, + json_build_object and + jsonb_agg, convert json5 values the + same way, so they are embedded as JSON rather than as strings. In the + other direction, + json values can be converted to json5 + implicitly; as the two types share their representation this is a + binary-coercible cast that involves no conversion, so a + json column can be changed to json5 without + rewriting the table. jsonb values can be converted with + an assignment cast. + + + Designing JSON Documents -- 2.55.0