json
The json module converts Tern values to JSON text and back. json.encode turns any struct, array, map, or basic value into compact JSON; json.decode fills a typed variable from JSON text and tells you whether it worked. This page covers exactly how each type maps to JSON, and what decode does with missing keys, unknown keys, null, and wrong types.
import json
struct User:
name: str
age: int
tags: [str]
fn main():
u = User("ada", 36, ["admin"])
text = json.encode(u)
print(text)
back = User("", 0, [])
if json.decode(text, &back):
print(back.name, back.age){"name":"ada","age":36,"tags":["admin"]}
ada 36There is no reflection in Tern: the compiler writes a dedicated encoder and decoder for each type you use with json, so both are fast and type-checked at compile time. Like Rust's serde derive, they are Tern code: a struct's or an enum's is put together from its fields, and the rest (numbers, strings, arrays, maps, Options, the scanner) is in library/std/json/.
How types map to JSON
| Tern type | JSON |
|---|---|
int | a number without a fraction: 42 |
float | a number, always with a fraction or exponent: 2.0, 0.1, 1e+20; NaN and infinity become null |
bool | true / false |
str | a string. ", \, and control characters are escaped; other bytes (UTF-8 text such as é) are written as they are |
[T] | an array |
{str: T} | an object |
{int: T} | an object whose keys are the numbers as strings: {"1": ...} |
| a struct | an object with one key per field, in declaration order |
Option[T] | null for None, the value for Some(v). Decoding, null or a missing key gives None |
| an enum | "Name" for a variant without fields; {"Name": value} or {"Name": {fields}} for one with |
An enum is its variant's name when the variant has no fields, and an object holding the fields under the name when it has some: one field is the value itself, several are an object (the "externally tagged" form Rust's serde uses). Decoding also accepts the name in another case or spelling: "banned", "BANNED", and "in_progress" all name InProgress.
import json
enum Status:
Active
InProgress
Banned
enum Shape:
Circle(radius: float)
Rect(w: float, h: float)
Empty
struct Account:
name: str
status: Status
shapes: [Shape]
fn main():
a = Account("ada", Status.InProgress, [Shape.Circle(1.5), Shape.Rect(2.0, 3.0), Shape.Empty])
print(json.encode(a))
s = Status.Active
ok = json.decode(`"banned"`, &s)
print(ok, s){"name":"ada","status":"InProgress","shapes":[{"Circle":1.5},{"Rect":{"w":2.0,"h":3.0}},"Empty"]}
true Status.BannedFunctions, tuples, ptr values, and recursive enums can't be converted; using one (or a struct or array containing one) with json is a compile error:
import json
struct Button:
label: str
on_click: fn(int) str
fn main():
b = Button("go", fn(n) "clicked")
print(json.encode(b))9: error: json.encode can't handle ButtonA field that may be absent or null is an Option:
import json
struct Profile:
name: str
email: Option[str]
age: Option[int]
fn main():
ps: [Profile] = []
ok = json.decode(`[{"name": "ada", "email": "ada@example.com"}, {"name": "bob", "email": null, "age": 41}]`, &ps)
print(ok, ps)
print(json.encode(ps[0]))true [Profile{name: "ada", email: Some("ada@example.com"), age: None}, Profile{name: "bob", email: None, age: Some(41)}]
{"name":"ada","email":"ada@example.com","age":null}encode
fn encode(value: T) strThe JSON text of any value whose type is in the table above. The output is compact (no spaces or newlines) and always valid JSON. Floats use the shortest text that reads back as the same number, so a float round-trips exactly.
import json
fn main():
print(json.encode([1, 2, 3]), json.encode({"a": 1.5}), json.encode({7: true}))
print(json.encode("say \"hi\"\n"), json.encode(0.1 + 0.2), json.encode(1.0 / 0.0))
empty: [str] = []
print(json.encode(empty), json.encode([[1], []]), json.encode("café"))[1,2,3] {"a":1.5} {"7":true}
"say \"hi\"\n" 0.30000000000000004 null
[] [[1],[]] "café"For a single string, the builtin json_quote does the same as json.encode without the import.
decode
fn decode(text: str, out: mut T) boolParses text as JSON and stores it in out, which you pass with &. Returns true on success. Decoding is all-or-nothing: if it returns false, out is exactly as it was, even if part of the text was valid. Whitespace around the value is allowed; anything else after it makes decoding fail.
Into a struct, it follows these rules:
- Missing keys keep the current value. Fill
outwith defaults before decoding, and keys the JSON leaves out keep them. This is how you merge a partial update. - Unknown keys are ignored, whatever their value (objects, arrays, anything valid).
nullkeeps the current value, like a missing key.- Keys are matched exactly:
"Name"does not fillname. If a key appears twice, the last one wins. - A nested struct is merged the same way:
{"home": {"city": "Rome"}}changes onlyhome.city.
Arrays and maps are replaced, not merged: "tags": ["c"] makes tags exactly ["c"].
import json
struct Address:
city: str
zip: str
struct Profile:
name: str
age: int
home: Address
tags: [str]
fn main():
p = Profile("ada", 36, Address("London", "N1"), ["a", "b"])
patch = `{"age": 37, "home": {"city": "Rome"}, "tags": ["c"], "extra": [1, {"x": null}], "name": null}`
print(json.decode(patch, &p))
print(p)true
Profile{name: "ada", age: 37, home: Address{city: "Rome", zip: "N1"}, tags: ["c"]}Type mismatches
A value of the wrong type makes the whole decode fail:
| Field type | Accepts | Rejects |
|---|---|---|
int | whole numbers, including 4.0 and 1e2 | 4.5, "5", true, numbers beyond 64 bits |
float | any number (3 becomes 3.0) | "3.5", true |
bool | true, false | 1, "true" |
str | strings (with \n, \", é, and surrogate-pair escapes decoded) | numbers, true |
[T] | an array whose every element fits T | null elements, a lone value |
{str: T} | an object | an array |
{int: T} | an object whose keys are whole numbers as strings ("12") | any other key |
| a struct | an object | an array, null at the top level |
import json
struct Item:
name: str
qty: int
fn main():
it = Item("pen", 1)
print(json.decode(`{"qty": 4.0}`, &it), it.qty)
print(json.decode(`{"qty": 4.5}`, &it), it.qty)
print(json.decode(`{"qty": "5"}`, &it), it.qty)
print(json.decode(`{"name": "cup", "qty": 2} extra`, &it), it.name)
print(json.decode(`{"name": "cup",}`, &it), json.decode("{'name': 'cup'}", &it))
xs = [9]
print(json.decode("[1, null]", &xs), xs)
print(json.decode("[1, 2.0, -3]", &xs), xs)
ids: {int: str} = {}
print(json.decode(`{"1": "a", "22": "b"}`, &ids), ids)true 4
false 4
false 4
false pen
false false
false [9]
true [1, 2, -3]
true {1: "a", 22: "b"}The parser is slightly more lenient than the JSON standard about numbers (it accepts +5 and 007), but not about structure: trailing commas, single quotes, comments, and unquoted keys are all rejected.
Decoding plain values
out can be any JSON-compatible type, not just a struct:
import json
fn main():
scores: {str: [int]} = {}
ok = json.decode(`{"ada": [90, 85], "bob": []}`, &scores)
print(ok, scores["ada"], len(scores["bob"]))
n = 0
s = ""
print(json.decode(" 42 ", &n), n, json.decode("\"caf\\u00e9\"", &s), s)true [90, 85] 0
true 42 true caféschema
json.schema[T]() is the JSON Schema (2020-12) of what json.encode writes for a type T, as a string. Like the encoder, it is generated while compiling, so it costs nothing at run time. Structs go under $defs and are referred to with $ref (so a struct can contain arrays of itself), and every field is required, because json.encode always writes all of them. The openapi package builds API descriptions from it.
import json
struct Item:
sku: str
qty: int
struct Order:
id: int
items: [Item]
notes: {str: str}
fn main():
print(json.schema[Item]())
print(json.schema[[int]]())
print(json.schema[Order]().contains(`"items":{"type":"array","items":{"$ref":"#/$defs/Item"}}`)){"$ref":"#/$defs/Item","$defs":{"Item":{"type":"object","properties":{"sku":{"type":"string"},"qty":{"type":"integer","format":"int64"}},"required":["sku","qty"]}}}
{"type":"array","items":{"type":"integer","format":"int64"}}
trueEnums and tuples have no JSON form, so json.schema refuses them, as json.encode does. A struct from another module is named with its module (models.User), and a generic one with its type arguments (Pair_int_str).
Working with JSON of unknown shape
decode needs a type to fill. For JSON whose shape varies or isn't known ahead of time (a field that is sometimes a number and sometimes a string, a webhook with dozens of optional fields, a config you only read a few keys of), json.parse(text) gives a json.Value: an enum of Null, Bool(b), Num(x, text), Str(s), Arr(items) and Obj(keys, vals).
Lookups never fail: v.field(key) and v.at(i) give Null when the key or element isn't there (or v isn't an object or array), so they chain, and str_or, int_or, float_or, bool_or end the chain with a default. match on the Value when you need to know its kind.
import json
fn main() Result[int, str]:
v = json.parse(`{"event": "order.paid", "data": {"id": 9007199254740993, "items": [{"sku": "A1", "qty": 2}, {"sku": "B7"}]}}`)?
print(v.field("event").str_or(""), v.field("data").field("id").int_or(0))
for it in v.field("data").field("items").elems():
print(it.field("sku").str_or("?"), it.field("qty").int_or(1))
print(v.field("data").field("missing").at(3).str_or("default"), v.field("data").fields())
match v.field("event"):
Str(s):
print("a string of", len(s), "bytes")
_:
print("not a string")
print(json.dump(v.field("data").field("items").at(1)))
print(json.parse(`{"a" 1}`).is_err())
return Ok(0)order.paid 9007199254740993
A1 2
B7 1
default ["id", "items"]
a string of 10 bytes
{"sku":"B7"}
truejson.parse(text) Result[json.Value, str]: the error says what and at which byte (json: expected:after a key at byte 5).v.fields() [str](an object's keys, in order),v.elems() [json.Value],v.size() int.v.field(key)scans the object's keys, which is fastest for the small objects most JSON has. For many lookups in an object with thousands of keys, index it once:m = v.to_map()gives a{str: json.Value}(a repeated key keeps its last value).json.dump(v) strwrites a Value back as compact JSON. Numbers keep the text they were written with, soint_orreads integers past 2^53 exactly anddumpdoesn't reformat them.- Decoding into a struct with
json.decodeis faster and checks the shape for you; use a Value for the parts that really vary.
A complete example
Loading a configuration file with defaults, validating it, and saving it back:
import json
import fs
struct Server:
host: str
port: int
struct Config:
name: str
workers: int
debug: bool
servers: [Server]
limits: {str: int}
fn defaults() Config:
return Config("app", 4, false, [Server("localhost", 8080)], {"max_body_mb": 16})
fn load(path: str, cfg: mut Config) str:
if not fs.exists(path):
return "no config file; using defaults"
if not json.decode(fs.read(path), &cfg):
return "config is not valid JSON for Config; using defaults"
if cfg.workers < 1:
cfg.workers = 1
return "loaded " + path
fn main():
path = "/tmp/tern_json_config.json"
fs.write(path, `{"name": "shop", "workers": 0, "servers": [{"host": "10.0.0.2", "port": 9000}], "comment": "ignored"}`)
cfg = defaults()
print(load(path, &cfg))
print(cfg.name, cfg.workers, cfg.debug, cfg.servers[0].host, cfg.limits)
cfg.debug = true
fs.write(path, json.encode(cfg))
print(fs.read(path))
fs.write(path, `{"workers": "many"}`)
bad = defaults()
print(load(path, &bad), bad.workers)
fs.remove(path)loaded /tmp/tern_json_config.json
shop 1 false 10.0.0.2 {"max_body_mb": 16}
{"name":"shop","workers":1,"debug":true,"servers":[{"host":"10.0.0.2","port":9000}],"limits":{"max_body_mb":16}}
config is not valid JSON for Config; using defaults 4Speed
Encoding and then decoding 300k structs three times (bench/tern/json.tn, one thread): Tern runs 3.74G instructions in 107 MB, Rust's serde_json 5.20G in 178 MB, and Go's encoding/json 20.6G in 262 MB. The numbers are in bench/results.md.