---
title: "10.5 JSON"
url: https://una-lang.org/en/learn/collections/json/
release: v0.4.0
edition: "0.2"
---

# 10.5 JSON

## 10.5.1 What JSON is

**JSON** is a way to write data as text, so that two programs can exchange it: a shop and its accounting service, a warehouse and a product feed. It has six kinds of value:

- `null`, which means "nothing";
- `true` and `false`;
- numbers, such as `1990` or `19.90`;
- strings, text between double quotes, such as `"LAMP-01"`;
- arrays, values in order between brackets, such as `["new", "sale"]`;
- objects, named fields between braces, such as `{"sku": "LAMP-01", "cents": 1990}`. Each field has a name, a string, and a value of any kind.

A product record of a feed is one object: `{"sku": "LAMP-01", "cents": 1990, "tags": ["new"]}`. Reading such text into a value the program can use is **parsing**, and writing a value out as text is **serializing**.

## 10.5.2 Why JSON needs a parser

A JSON record is only text, and a program could try to read it by cutting the text, as a person might read it by eye. Here is a function that finds the price by taking what comes after the first comma and the next colon:

```una include="steps/21-json-by-hand/src/byhand.una" title="steps/21-json-by-hand/src/byhand.una" verified="check, run"
module byhand

--- The price in a product record, read by cutting the text: it expects the SKU first and the
--- price second, and nothing else.
price_by_hand(text: Text) -> Option[Int]
=
  let second = text.split(on: ",").at(index: 1).or_else(default: "")
  let value = second.split(on: ":").at(index: 1).or_else(default: "")
  value.replace(pattern: "\}", by: "").trim.to_int()

pub main() -> Unit
  uses @console: Console[print]
=
  let usual = "\{\"sku\": \"LAMP-01\", \"cents\": 1990\}"
  let reordered = "\{\"cents\": 1990, \"sku\": \"LAMP-01\"\}"
  let tagged = "\{\"sku\": \"LAMP-01\", \"tags\": [\"new\", \"sale\"], \"cents\": 1990\}"
  @console.print("{price_by_hand(usual)} {price_by_hand(reordered)} {price_by_hand(tagged)}")
```

`una run .` prints:

```text include="steps/21-json-by-hand/expected/output.txt"
Some(1990) None None
```

The first record works. The other two hold the same price, and the function finds nothing: in one the fields come in another order, which JSON allows, and in the other an array holds a comma of its own. Code that cuts text depends on how the sender happened to write it. A **parser** reads the text by the rules of JSON, whatever the order of the fields or the spaces, and says exactly where the text breaks those rules.

## 10.5.3 How to read and write JSON

### 10.5.3.1 The kind `Json`

The prelude reads JSON into a value of the sum kind `Json`, with one variant for each kind of JSON value:

| JSON | Variant of `Json` | What it holds |
| --- | --- | --- |
| `null` | `Null` | nothing |
| `true`, `false` | `Boolean(value)` | a `Bool` |
| a whole number, such as `1990` | `Number(value)` | an `Int`, exact at any size |
| a number with a fraction or an exponent, such as `19.90` | `Decimal(text)` | the number as written in the input |
| a string | `Str(value)` | a `Text` |
| an array | `Array(items)` | a `List[Json]` |
| an object | `Object(fields)` | a `Map[Text, Json]`, so everything of [section 10.4](https://una-lang.org/en/learn/collections/maps/#s10-4) applies |

The step of this part reads one value of each kind, and `describe` has one arm per variant:

```una include="steps/22-json-forms/src/records.una#describe" title="steps/22-json-forms/src/records.una"
--- What a parsed value is: one arm for each variant of `Json`.
describe(json: Json) -> Text
=
  when json
    is Null -> "null"
    is Boolean(value) -> "yes or no: {value}"
    is Number(value) -> "a whole number: {value}"
    is Decimal(text) -> "a number with a fraction: {text}"
    is Str(value) -> "a string: {value}"
    is Array(items) -> "an array of {items.len} items"
    is Object(fields) -> "an object with the fields {fields.keys()}"
```

### 10.5.3.2 Parsing: `parse_json` and its clause

`text.parse_json()` parses a text. The text may not be JSON at all, so the call can fail with `JsonError`, and it takes a clause on the line under it, as every call that can fail does ([section 7.3](https://una-lang.org/en/learn/failure/handling-a-failure-the-clauses/#s7-3)). `if error use Null` carries on with `Null` in place of the value.

```una include="steps/22-json-forms/src/records.una#L38-L42" title="steps/22-json-forms/src/records.una"
  let inputs = ["null", "true", "1990", "19.90", "\"LAMP-01\"", "[1, 2, 3]", "\{\"sku\": \"LAMP-01\", \"cents\": 1990\}"]
  for text in inputs
    let value = text.parse_json()
      if error use Null
    @console.print(describe(value))
```

```text include="steps/22-json-forms/expected/output.txt#L1-L7"
null
yes or no: true
a whole number: 1990
a number with a fraction: 19.90
a string: LAMP-01
an array of 3 items
an object with the fields ["cents", "sku"]
```

The inputs are Una texts. In Una text, `{` starts an interpolation, so a literal brace is written `\{` and `\}`, and a double quote is `\"` ([section 3.1](https://una-lang.org/en/learn/text-and-conditions/text/#s3-1)).

### 10.5.3.3 Reading a field: `when`, then `get`

A field is read in two steps. A `when` checks that the value is an object and binds its fields; then `get` reads one field, as on any map. Each step can find nothing, so each says what to do then. `tags` reads the array `tags` of a record, and keeps the strings in it:

```una include="steps/22-json-forms/src/records.una#tags" title="steps/22-json-forms/src/records.una"
--- The tags of a product record: the strings in its array `tags`, or `[]` when it has none.
tags(record: Json) -> List[Text]
=
  let listed = when record
    is Object(fields) -> fields.get(key: "tags").or_else(default: Null)
    else -> Null
  let items = when listed
    is Array(items) -> items
    else -> []
  let edit found: List[Text] = []
  for item in items
    when item
      is Str(value) ->
        found = found.append(item: value)
      else -> unit
  found
```

```una include="steps/22-json-forms/src/records.una#L43-L45" title="steps/22-json-forms/src/records.una"
  let record = "\{\"sku\": \"LAMP-01\", \"tags\": [\"new\", 7, \"sale\"]\}".parse_json()
    if error use Null
  @console.print("tags: {tags(record)} and {tags(Null)}")
```

```text include="steps/22-json-forms/expected/output.txt#L8"
tags: ["new", "sale"] and []
```

The `7` in the array is a `Number`, not a `Str`, so the `else` arm skips it: it gives `unit`, the only value of the type `Unit`, which does nothing. `Null`, which is not an object, has no tags.

### 10.5.3.4 Keeping the failure: `attempt` and `JsonError`

When a text is not JSON, the failure is a value of the kind `JsonError`, and each variant carries `at`, the position where reading stopped, counted in characters from 0:

- `Syntax(at)`: the first character where no valid JSON can continue, or the end of the text when it ends too early;
- `DuplicateKey(at)`: an object names the same field twice;
- `TooDeep(at)`: arrays and objects nest more than 512 levels deep;
- `NumberTooLong(at)`: a whole number of more than 4300 digits.

`attempt` keeps the outcome as a value instead of handling it on the spot ([section 7.4](https://una-lang.org/en/learn/failure/failures-as-values-attempt-and-result/#s7-4)): `Ok` with the `Json`, or `Err` with the `JsonError`.

```una include="steps/22-json-forms/src/records.una#parsed" title="steps/22-json-forms/src/records.una"
--- A text read as JSON, kept as a value: `Ok` with the JSON, or `Err` with where it broke.
parsed(text: Text) -> Result[Json, JsonError] = attempt text.parse_json()
```

```una include="steps/22-json-forms/src/records.una#L46-L49" title="steps/22-json-forms/src/records.una"
  let trailing = parsed("[1, 2,]")
  let twice = parsed("\{\"sku\": \"LAMP-01\", \"sku\": \"RUG-07\"\}")
  let empty = parsed("")
  @console.print("{trailing} {twice} {empty}")
```

```text include="steps/22-json-forms/expected/output.txt#L9"
Err(Syntax(6)) Err(DuplicateKey(19)) Err(Syntax(0))
```

In `[1, 2,]`, position 6 is the `]` after the comma, where JSON wants another value. The second text names `sku` twice, and the second `sku` starts at position 19. The empty text ends before any value, at position 0.

### 10.5.3.5 Writing: build a `Json`, then `to_json`

To write JSON, build a `Json` value with the variants, and call `to_json`. An object is a `Map[Text, Json]` wrapped in `Object`:

```una include="steps/22-json-forms/src/records.una#L50-L56" title="steps/22-json-forms/src/records.una"
  let edit fields: Map[Text, Json] = empty_map()
  edit fields.set(key: "sku", value: Str(value: "LAMP-01"))
  edit fields.set(key: "tags", value: Array(items: [Str(value: "new"), Null]))
  edit fields.set(key: "on_sale", value: Boolean(value: false))
  @console.print(Object(fields).to_json())
  let note = "a \"bright\" lamp"
  @console.print(note.quote_json())
```

```text include="steps/22-json-forms/expected/output.txt#L10-L11"
{"on_sale":false,"sku":"LAMP-01","tags":["new",null]}
"a \"bright\" lamp"
```

`quote_json` writes one text as a JSON string, with its quotes escaped, for when you build JSON text yourself.

## 10.5.4 Reading and writing a product feed

The forms together. The step parses two records of a product feed, reads a price, and writes JSON back:

:::steps
```una include="steps/23-json/src/feed.una" title="steps/23-json/src/feed.una" verified="check, run"
module feed

--- The price in a product record of the catalog feed, or `None` when it has none.
price(record: Json) -> Option[Int]
=
  when record
    is Object(fields) ->
      let cents = fields.get(key: "cents").or_else(default: Null)
      when cents
        is Number(value) -> Some(value)
        else -> None
    else -> None

pub main() -> Unit
  uses @console: Console[print]
=
  let text = "\{\"sku\": \"LAMP-01\", \"cents\": 1990, \"tags\": [\"new\"]\}"
  let record = text.parse_json()
    if error use Null
  @console.print("{record}")
  @console.print("{price(record)}")
  let broken = "\{\"sku\": \"LAMP-01\",\}".parse_json()
    if error use Null
  @console.print("{price(broken)}")
  let edit fields: Map[Text, Json] = empty_map()
  edit fields.set(key: "sku", value: Str(value: "LAMP-01"))
  edit fields.set(key: "in_stock", value: Boolean(value: true))
  edit fields.set(key: "cents", value: Number(value: 1990))
  @console.print(Object(fields).to_json())
```

1. **`when record` with `is Object(fields)`.** Reading JSON is reading a sum kind: one arm for the variant you expect, and `else` for the rest. Then `fields.get(key: "cents")` is an ordinary map lookup, and `or_else(default: Null)` treats a missing field like a `null` one.
2. **`\{`, `\}` and `\"`.** JSON in a text literal: a literal brace is written `\{` and `\}`, and a quote is `\"`.
3. **`text.parse_json()` and `if error use Null`.** Parsing can fail, and the line under the call says what to do then: here, carry on with `Null`.
4. **`Object(fields).to_json()`.** Writing. `to_json` writes one canonical text: no spaces, and the keys of each object in order.
:::

`una run .` prints:

```text include="steps/23-json/expected/output.txt"
Object({"cents": Number(1990), "sku": Str("LAMP-01"), "tags": Array([Str("new")])})
Some(1990)
None
{"cents":1990,"in_stock":true,"sku":"LAMP-01"}
```

The first line is the interpolation of a `Json`, which shows the Una value, not JSON text. The keys come out sorted: a JSON object is a map, so the order of the input is not kept. The second record has a comma after its last field, which JSON does not allow, so it parses as `Null` and has no price.

## 10.5.5 How JSON behaves

### 10.5.5.1 One way to write each value

`to_json` writes a value in one canonical form: no spaces, the fields of every object in key order, and strings escaped the same way every time. So equal values always give the same text, and the text of a value read and written back does not depend on how the sender spaced or ordered it.

### 10.5.5.2 Strict reading

`parse_json` reads exactly one JSON value, with spaces allowed around it, and nothing else. It refuses what JSON does not allow: comments, a comma after the last item, single quotes, `NaN`, a leading `+`, a leading zero before other digits, as in `01`, and a field named twice.

### 10.5.5.3 Interpolation shows the Una value

`"{record}"` writes a `Json` in its Una form, such as `Object({"cents": Number(1990)})`, which helps when you look for a mistake. `to_json` writes JSON.

### 10.5.5.4 Numbers with a fraction

> [!WARNING]
> A JSON number with a fraction, such as `19.90`, is a `Decimal`, not a `Number`, so `is Number(value)` does not match it. Keep money in whole cents, in JSON as in Una. Edition `0.2` has no type for numbers with a fraction; the preview editions add them ([chapter 2](https://una-lang.org/en/learn/numbers/)).

### 10.5.5.5 Read once, then use typed values

A misspelt field name, such as `"cent"`, still checks: no checker knows which fields a text will hold, and `get` gives `None` when the program runs. So read the JSON in one place, into a record with typed fields, as the day-to-day program's `read_line` does, and let the rest of the program use the record. A misspelt field of a record does not check.

## 10.5.6 Choosing how to read a field

:::decide
**Which to use:**

| You want to… | Use |
| --- | --- |
| A value of one variant, and nothing for the rest | `when` with that variant's arm and `else` |
| A field that may be missing, read as `Null` | `fields.get(key: k).or_else(default: Null)`, then `when` |
| A field with a sensible default | read it as an `Option`, then `or_else` |
| Every failure, with where the text broke | `attempt text.parse_json()`, then `when` on `Ok` and `Err` |
| JSON text from your own values | build a `Json`, then `to_json` |
:::

## 10.5.7 Check yourself: JSON

These lines read a record and write it back. Predict the line they print:

```una include="steps/22-json-forms/src/records.una#L57-L60" title="steps/22-json-forms/src/records.una"
  let input = "\{\"sku\": \"RUG-07\", \"cents\": 4500, \"active\": true\}"
  let product = input.parse_json()
    if error use Null
  @console.print(product.to_json())
```

:::answer Show the answer
```text include="steps/22-json-forms/expected/output.txt#L12"
{"active":true,"cents":4500,"sku":"RUG-07"}
```

The record parses as an `Object`, whose fields form a map, so `to_json` writes them in key order, `active`, `cents`, `sku`, and with no spaces. The order of the input is not kept.
:::
