Home / Learn / 10 Collections

Release v0.4.0Edition 0.2

10.5 JSON

Page 6 of 11

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:

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:

steps/21-json-by-hand/src/byhand.unacheckrununa
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:

Output
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 applies

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

steps/22-json-forms/src/records.unauna
--- 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). if error use Null carries on with Null in place of the value.

steps/22-json-forms/src/records.unauna
  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))
Output
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).

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:

steps/22-json-forms/src/records.unauna
--- 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
steps/22-json-forms/src/records.unauna
  let record = "\{\"sku\": \"LAMP-01\", \"tags\": [\"new\", 7, \"sale\"]\}".parse_json()
    if error use Null
  @console.print("tags: {tags(record)} and {tags(Null)}")
Output
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:

attempt keeps the outcome as a value instead of handling it on the spot (section 7.4): Ok with the Json, or Err with the JsonError.

steps/22-json-forms/src/records.unauna
--- 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()
steps/22-json-forms/src/records.unauna
  let trailing = parsed("[1, 2,]")
  let twice = parsed("\{\"sku\": \"LAMP-01\", \"sku\": \"RUG-07\"\}")
  let empty = parsed("")
  @console.print("{trailing} {twice} {empty}")
Output
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:

steps/22-json-forms/src/records.unauna
  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())
Output
{"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/23-json/src/feed.unacheckrununa
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:

Output
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).

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

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:

steps/22-json-forms/src/records.unauna
  let input = "\{\"sku\": \"RUG-07\", \"cents\": 4500, \"active\": true\}"
  let product = input.parse_json()
    if error use Null
  @console.print(product.to_json())
Show the answer
Output
{"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.

Next:10.6 Day-to-day: a daily sales report