Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/elfrask/cls/llms.txt

Use this file to discover all available pages before exploring further.

The json module is part of the CLS core standard library and is available on every node. It provides two functions — parse and stringify — for moving data between JSON text and CLS runtime values. The module is backed by Rust’s serde_json crate, which means it handles the full JSON specification faithfully: objects, arrays, strings, numbers, booleans, and null all round-trip correctly. Custom classes can participate in serialization by defining a __toJson() magic method.

​
Import

import "json" as json;
Or import individual functions: 
from "json" import parse, stringify;

​
Function Reference

​
json.parse(text: String) -> Any

Parses a JSON string and returns the corresponding CLS value. The mapping from JSON to CLS is:
JSON typeCLS value
nullnull
true / falsebool
Integer numberint
Decimal numberfloat
"string"String
[...] arrayArray
{...} objectRecord
Throws a RuntimeError if the input is not valid JSON.

​
json.stringify(val: Any) -> String

Serializes a CLS value to a compact JSON string. The mapping from CLS to JSON is:
CLS valueJSON output
nullnull
booltrue / false
intinteger number
floatdecimal number
String"string"
Array[...]
Record{...}
class instance with __toJson()result of __toJson()
any other valuenull

​
Examples

​
Parsing JSON text

import "json" as json;

var data = json.parse('{"name": "CLS", "version": 2, "active": true}');

print(data["name"]);     # CLS
print(data["version"]);  # 2
print(data["active"]);   # true

​
Parsing nested structures

import "json" as json;

var payload = json.parse('{"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}');

for each user in (payload["users"]) {
    print(user["id"], "-", user["name"]);
};
# 1 - Alice
# 2 - Bob

​
Stringifying a record

import "json" as json;

var config = { "host": "localhost", "port": 8080, "debug": false };
var text = json.stringify(config);
print(text);   # {"debug":false,"host":"localhost","port":8080}

​
Round-trip

import "json" as json;

var original = { "x": 1, "y": [2, 3, 4], "z": null };
var text = json.stringify(original);
var parsed = json.parse(text);

print(parsed["x"]);     # 1
print(parsed["y"][0]);  # 2
print(parsed["z"]);     # null

​
__toJson() Magic Method

If you call json.stringify on a class instance that defines a __toJson() method, the interpreter calls that method and serializes its return value instead of the instance itself. This lets you control exactly how your objects appear in JSON output. 
import "json" as json;

class Point {
    export var x: float = 0.0;
    export var y: float = 0.0;

    function __toJson() -> Any {
        return { "x": me.x, "y": me.y };
    };
};

var p = Point();
p.x = 1.5;
p.y = 2.5;

print(json.stringify(p));   # {"x":1.5,"y":2.5}
Without __toJson, a class instance will serialize as null because the underlying Value::Object variant has no automatic JSON representation.

​
Edge Cases

import "json" as json;

# null round-trips correctly
print(json.stringify(null));         # null
print(json.parse("null"));           # null

# Booleans
print(json.stringify(true));         # true
print(json.stringify(false));        # false

# Integers vs floats
print(json.stringify(42));           # 42
print(json.stringify(3.14));         # 3.14

# Empty array and object
print(json.stringify([]));           # []
print(json.stringify({}));           # {}

# Invalid JSON throws
try {
    json.parse("not json");
} catch (e) {
    print("parse error:", e);
};

Build docs developers (and LLMs) love

Get started for freeTalk to us