---
title: "parse_json"
url: https://una-lang.org/en/docs/std/prelude/parse_json/
release: v0.4.0
edition: "0.2 and later"
source: https://github.com/una-lang/una/blob/v0.4.0/docs/std/listing.json
---

# parse_json

A function of the prelude, in scope in every module. Edition 0.2 and later.

```una
pub parse_json(t: Text) -> Json
  fails JsonError
```

The one JSON value of `t` (`spec/23 §3`).

## Parameters

- `t`: the text

## Returns

`Json`: the one JSON value that `t` writes\, with optional white space \(U\+0020\, U\+0009\, U\+000A and U\+000D\) before and after it and nothing else\; there is no limit on its size beyond the memory budget\, and a run over it ends with U6003 at the call\; when `t` is not one value\, the failure is the first error in reading order\; the result and the failure carry the labels of `t` \(`spec/23 §5`\)\, so with a labeled `t`\, `if error pass` and `if error fail` are U4002\, and `attempt` or `if error use` handles the failure.

## Fails with

- `Syntax` when `t` is not one JSON value of RFC 8259\: there are no comments\, trailing commas\, `NaN`\, `Infinity`\, single quotes or byte order mark\, no leading `+` or leading zero in a number\, and no lone surrogate\, raw scalar value below U\+0020 or unknown escape in a string\; `at` is the scalar position\, from 0\, of the first scalar value where no JSON text can continue\, or the length of `t` when it ends early
- `TooDeep` when arrays and objects nest more than 512 deep\; `at` is the scalar position\, from 0\, of the bracket that opens the 513th level
- `DuplicateKey` when an object has two equal keys\, compared after unescaping\; `at` is the scalar position\, from 0\, of the second one
- `NumberTooLong` when an integer has more than 4300 digits\; `at` is the scalar position\, from 0\, of its first character\; a number with a fraction or an exponent has no such limit

## See also

[`JsonError`](https://una-lang.org/en/docs/std/prelude/JsonError/), [`to_json`](https://una-lang.org/en/docs/std/prelude/to_json/), [`Json`](https://una-lang.org/en/docs/std/prelude/Json/)

## Cost

Time `O(n + Σ k log k)` (spec/23 §6), where:

- `n`: the length of `t` in scalar values
- `k`: the number of keys of one object\; `Σ` sums `k log k` over the objects of `t`

## Example

`src/shop.una`

```una
module shop

--- An order read from JSON, and why a text is not one JSON value.
order(raw: Text) -> Text
=
  let outcome = attempt parse_json(raw)
  when outcome
    is Ok(value) -> written(value)
    is Err(failure) -> reason(failure)

written(value: Json) -> Text
=
  let text = value.to_json()
  "read {text}"

reason(failure: JsonError) -> Text
=
  when failure
    is Syntax(at) -> "not JSON at {at}"
    is TooDeep(at) -> "nested too deep at {at}"
    is DuplicateKey(at) -> "a key twice at {at}"
    is NumberTooLong(at) -> "a number too long at {at}"

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print(order("\{\"lamp\": 3, \"desk\": 1\}"))
  @console.print(order("[1, 2,]"))
  @console.print(order("\{\"lamp\": 3, \"lamp\": 4\}"))
```

`una run .` prints:

```text
read {"desk":1,"lamp":3}
not JSON at 6
a key twice at 12
```

## Specification

- [`spec/23 §3`](https://una-lang.org/en/docs/spec/23-json/#s3)

Generated from the standard modules of una v0.4.0 ([`docs/std/listing.json`](https://github.com/una-lang/una/blob/5fec93d88932b333feec25e589355a2cb34c37b5/docs/std/listing.json), which is not part of the specification). The specification governs: [`spec/14 §1`](https://una-lang.org/en/docs/spec/14-standard-library/#s1).
