Home / Learn / 10 Collections
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:
null, which means "nothing";trueandfalse;- numbers, such as
1990or19.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:
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:
Some(1990) None NoneThe 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:
--- 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.
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))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:
--- 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 let record = "\{\"sku\": \"LAMP-01\", \"tags\": [\"new\", 7, \"sale\"]\}".parse_json()
if error use Null
@console.print("tags: {tags(record)} and {tags(Null)}")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): Ok with the Json, or Err with the JsonError.
--- 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() let trailing = parsed("[1, 2,]")
let twice = parsed("\{\"sku\": \"LAMP-01\", \"sku\": \"RUG-07\"\}")
let empty = parsed("")
@console.print("{trailing} {twice} {empty}")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:
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()){"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:
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())when recordwithis Object(fields). Reading JSON is reading a sum kind: one arm for the variant you expect, andelsefor the rest. Thenfields.get(key: "cents")is an ordinary map lookup, andor_else(default: Null)treats a missing field like anullone.\{,\}and\". JSON in a text literal: a literal brace is written\{and\}, and a quote is\".text.parse_json()andif error use Null. Parsing can fail, and the line under the call says what to do then: here, carry on withNull.Object(fields).to_json(). Writing.to_jsonwrites one canonical text: no spaces, and the keys of each object in order.
una run . prints:
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:
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
{"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.