Tern

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)
Output
{"name":"ada","age":36,"tags":["admin"]}
ada 36

There 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 typeJSON
inta number without a fraction: 42
floata number, always with a fraction or exponent: 2.0, 0.1, 1e+20; NaN and infinity become null
booltrue / false
stra 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 structan 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)
Output
{"name":"ada","status":"InProgress","shapes":[{"Circle":1.5},{"Rect":{"w":2.0,"h":3.0}},"Empty"]}
true Status.Banned

Functions, 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:

Does not compile
import json

struct Button:
    label: str
    on_click: fn(int) str

fn main():
    b = Button("go", fn(n) "clicked")
    print(json.encode(b))
Compiler output
9: error: json.encode can't handle Button

A 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]))
Output
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) str

The 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é"))
Output
[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) bool

Parses 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 out with 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).
  • null keeps the current value, like a missing key.
  • Keys are matched exactly: "Name" does not fill name. If a key appears twice, the last one wins.
  • A nested struct is merged the same way: {"home": {"city": "Rome"}} changes only home.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)
Output
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 typeAcceptsRejects
intwhole numbers, including 4.0 and 1e24.5, "5", true, numbers beyond 64 bits
floatany number (3 becomes 3.0)"3.5", true
booltrue, false1, "true"
strstrings (with \n, \", é, and surrogate-pair escapes decoded)numbers, true
[T]an array whose every element fits Tnull elements, a lone value
{str: T}an objectan array
{int: T}an object whose keys are whole numbers as strings ("12")any other key
a structan objectan 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)
Output
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)
Output
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"}}`))
Output
{"$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"}}
true

Enums 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)
Output
order.paid 9007199254740993
A1 2
B7 1
default ["id", "items"]
a string of 10 bytes
{"sku":"B7"}
true
  • json.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) str writes a Value back as compact JSON. Numbers keep the text they were written with, so int_or reads integers past 2^53 exactly and dump doesn't reformat them.
  • Decoding into a struct with json.decode is 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)
Output
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 4

Speed

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.

Source: docs/std/json.md. Every example on this page is compiled and run by tern x test docs.