Home / Docs / Specification
23. JSON
Status: Normative, v0.2 (ADR 0073 and its amendments of 2026-10-07).
The prelude reads and writes JSON (RFC 8259): a kind for JSON values, a parser that fails with a declared kind, and one canonical way of writing.
Editions. The constructs of this chapter exist only in packages of edition 0.2 and later (spec/13 §7). In edition 0.1, Json, JsonNumber, JsonError, parse_json, to_json, quote_json and is_json_number are ordinary names.
1. The kind
-
Values. The prelude declares:
unapub kind Json = | Null | Boolean(value: Bool) --- An exact integer: a JSON number with neither a fraction nor an exponent. Other numbers are `Decimal`. | Number(value: Int) | Decimal(text: JsonNumber) | Str(value: Text) | Array(items: List[Json]) | Object(fields: Map[Text, Json]) pub kind JsonNumber = Text where is_json_number(it)is_json_number(t: Text) -> Boolis an opaque prelude predicate. It is true exactly whentmatches thenumberproduction of RFC 8259 §6 and has a fraction or an exponent, soNumberandDecimalnever hold the same number (ADR 0073 amendment). -
Names. A user kind named
Json,JsonNumberorJsonErroris U1002, as forMap(spec/21 §1). A user variant named like a variant ofJsonorJsonErrorshadows it in its module, as a userSomeshadowsOption's (ADR 0073, amendment of 2026-10-07). -
Numbers. A JSON number with neither a fraction nor an exponent is
Number, exact at any size. Every other number isDecimal, whosetextis the number as written in the input. -
Objects are maps ordered by their keys (spec/21 §1 rule 3), so the order of the input is not kept.
-
Equality is structural, as for any kind. Two
Decimals are equal when their texts are:1.0and1.00differ.
2. Functions
| Function | Type | Contract |
|---|---|---|
parse_json(t: Text) |
Json fails JsonError |
§3 |
to_json(j: Json) |
Text |
§4 |
quote_json(t: Text) |
Text |
the string literal of §4 rule 2 |
They are prelude functions, called with method syntax as those of spec/22 §2 are: t.parse_json(), j.to_json(), t.quote_json().
3. Parsing
-
Grammar.
parse_json(t)reads exactly one JSON value (RFC 8259 §2 to §7), with optional whitespace (U+0020, U+0009, U+000A, U+000D) before and after it, and nothing else. There are no comments, no trailing commas, noNaNorInfinity, no single quotes, and no byte order mark. A number has no leading zero before other digits, and no leading+. -
Strings.
- The escapes are
\",\\,\/,\b,\f,\n,\r,\tand\uXXXX, with hex digits in either case. A high surrogate escape followed by a low one gives one scalar value. - A lone surrogate, a raw scalar value below U+0020, or any other escape is a syntax error.
- The escapes are
-
Duplicate keys. An object with two equal keys, compared after unescaping, fails with
DuplicateKeyat the second one. -
Depth. Arrays and objects nest at most 512 deep. The bracket that opens the 513th level fails with
TooDeepat that bracket. -
Failures. The prelude declares:
unapub kind JsonError = Syntax(at: Int) | TooDeep(at: Int) | DuplicateKey(at: Int) | NumberTooLong(at: Int)atis a position in scalar values, as in spec/22 §1.- The failure is the first error in reading order:
Syntaxat the first scalar value where no valid JSON text can continue, or at the end oftwhen it ends early. In a\uescape, that is the first character that cannot continue a valid escape:"\uD800fails at 7,"\uDC00at 4, theCthat makes it a lone low surrogate. NumberTooLongat the first character of an integer of more than 4300 digits. A number with a fraction or an exponent has no such limit. (2026-10-18, #914.) The same bound, 4300 digits, holds forparse_int(spec/22 §4) andto_int(spec/14 §1).
-
Size. There is no limit beyond the memory budget (spec/11 §7).
parse_jsonandto_jsoncheck the budget as they go, every 4096 values and every 4096 scalar values of a string, so a run over its budget ends with U6003 at the call (#314).
4. Writing
- Canonical form.
to_json(j)writesjwith no whitespace:Nullasnull, andBooleanastrueorfalse;Numberin decimal, with a leading-when negative;Decimalas itstext;Stras the string literal of rule 2;Arrayas[, its items separated by,, then];Objectas{, its entries in key order ("key":value, with the key written as in rule 2) separated by,, then}.
- String literals.
- A string is written between
"characters. "and\are escaped with a backslash.- U+0008, U+000C, U+000A, U+000D and U+0009 are written as
\b,\f,\n,\rand\t. - Every other scalar value below U+0020, and U+007F, U+2028, U+2029, U+202A to U+202E and U+2066 to U+2069, are written as
\ufollowed by four lowercase hex digits. - Every other scalar value is written as itself.
- A string is written between
- Round trip.
parse_json(to_json(j)) == jfor everyjwhose arrays and objects nest at most 512 deep;to_jsonwrites deeper values, whichparse_jsonthen refuses withTooDeep. For everytthatparse_jsonaccepts,to_json(parse_json(t))is a fixed point ofto_json ∘ parse_json. - Interpolation of a
Jsonwrites its Una form (spec/11 §5), not JSON.
5. Information flow
- Parsing. The result of
parse_json(t)and its failure are labeled with the labels oft(spec/14 §1). A value bound from the result bywhentakes that label as its top label (spec/07 §7 rule 3). Whether the call fails, and where, depends ont:attemptgives aResultlabeled liket;if error useruns under a program counter raised by those labels, and its value carries them;if error passandif error failare U4002 when those labels are notpublic(spec/07 §3 rule 3).
- Constructing. In editions
0.2and0.3, the positions ofJsonare unlabeled, sopublic. A labeled value given to aJsonconstructor is U4001 (spec/07 §7 rule 2). A labeled text reaches JSON through a policy (spec/07 §5), or throughquote_jsonand interpolation. (v0.4, ADR 0073 J5 as amended on 2026-11-09, accepted on 2026-11-10, #917.) In edition0.4and later, aJsonvalue has one label, its top label; its positions staypublicin its type, so no signature changes. A call ofBoolean,Number,Decimal,Str,ArrayorObjectaccepts arguments at any label, and its result is labeled with the join of every label of every argument (spec/07 §7 rule 3: list elements, map keys and values, the top labels of nestedJsonvalues) and of nothing else.Null,Array([])andObjectof an empty map arepublic; a constructor under a raised program counter is raised by the branch join (spec/07 §7 rule 2), as any expression is. Refinements are kept: the text ofDecimalstill provesis_json_number. A value read back from a labeledJsonis raised by its top label (spec/07 §7 rule 3) andto_jsoncarries it (rule 3), so the U4001 or U4003 of a labeledJsonis where it reaches a lower declared type or a sink, never at the constructor. The rule is coarser than a label per position: apublicfield beside asecretone reads assecret. User kinds and the other kinds of the standard library keep their fields' declared labels. - Writing. The result of
to_json(j)carries the labels ofj, and the result ofquote_json(t)those oft.
6. Dynamic semantics
- Complexity. For an input of n scalar values, with an object of k keys counted once for each object:
- parsing takes O(n + Σ k log k) time, which is O(n) when every object's keys arrive in order, as
to_jsonwrites them; - writing takes O(n) time for an output of n scalar values, except that writing a
Numberof d digits takes O(d²) for d at most 4300: anIntof more digits is never written, the run aborting with U6003 at the call ofto_json(spec/11 §7, #923), so no write exceeds that cost; - both take O(n) space.
- parsing takes O(n + Σ k log k) time, which is O(n) when every object's keys arrive in order, as
- No native recursion. Parsing and writing keep their own stack on the heap, and never recurse on the native stack over a value's depth (ADR 0060).
- Equivalence. Both engines use one implementation, and give the same value, text or failure for every input (spec/16 §5).
- Purity. The functions of §2 perform no operation and record no trace event.
7. Verification
The functions are uninterpreted beyond their types (spec/12 §2). is_json_number is opaque, so a JsonNumber is made by parsing or by checked (spec/11 §4).