JSON

Loft has built-in JSON support: any struct can be serialised to JSON with a format flag, and parsed back from JSON text. No annotations or code generation needed — it works on every struct automatically.

Serialisation — struct to JSON

Use the :j format flag inside a format string to produce JSON output. Field names become quoted keys; strings are escaped; numbers and booleans are written as JSON literals.

"{my_struct:j}"

struct User {
  id: integer,
  name: text,
  email: text
}

Parsing — JSON to struct

Call Type.parse(text) to create a struct from JSON text. Both JSON-style quoted field names ("name": value) and loft-style unquoted field names (name: value) are accepted. Missing fields get null sentinels. Extra fields in the input are silently skipped.

user = User.parse(json_text)

Vectors

Parse a JSON array into a vector of structs with vector<T>.parse(text).

scores = vector<Score>.parse("[{\"v\":1},{\"v\":2}]")

struct Score {
  value: integer
}

Parse Errors

After parsing, check #errors on the result to see what went wrong. Each error is a text string describing the problem and its location.

data = MyType.parse(bad_json)
for e in data#errors { log_warn(e) }

Nested Structs

Structs with struct-typed fields parse nested JSON objects automatically.

struct Address {
  city: text,
  zip: text
}

struct Contact {
  name: text,
  address: Address
}

fn main() {
  u = User { id: 42, name: "Alice", email: "alice@example.com" };
  json = "{u:j}";
  expected = `{{"id":42,"name":"Alice","email":"alice@example.com"}}`;
  assert(json == expected, "to json");

  bob = User.parse(`{{"id":7,"name":"Bob","email":"bob@test.org"}}`);
  assert(bob.id == 7, "parsed id: {bob.id}");
  assert(bob.name == "Bob", "parsed name");
  assert(bob.email == "bob@test.org", "parsed email");

  u2 = User.parse("{u:j}");
  assert(u2.id == u.id, "round-trip id");
  assert(u2.name == u.name, "round-trip name");

  bad = User.parse(`{{"id":"not_a_number","name":42}}`);
  errs = 0;
  for err in bad#errors {
    log_info("parse error: {err}");
    errs += 1;
  }
  assert(errs > 0, "expected parse errors, got {errs}");

  scores = vector<Score>.parse(`[{{"value":10}},{{"value":20}},{{"value":30}}]`);
  total = 0;
  for s in scores {
    total += s.value;
  }
  assert(total == 60, "vector sum: {total}");

  c = Contact.parse(`{{"name":"Carol","address":{{"city":"Amsterdam","zip":"1012"}}}}`);
  assert(c.name == "Carol", "nested name");
  assert(c.address.city == "Amsterdam", "nested city: {c.address.city}");
  assert(c.address.zip == "1012", "nested zip");

Missing fields get null

When a field is absent from the JSON, the struct field gets its null sentinel. For text, that is the NUL character \0 (not the empty string ""); for integer it is the minimum i32 value. Check with ! before use, or assign a default with ??.

  partial = User.parse(`{{"id":1}}`);
  assert(partial.id == 1, "partial id");
  assert(!partial.name, "missing name is null");
}