json Module

Work with JSON values and JSON files.

import { json } from "system";

Availability

Available in the Main script only.

Table of Contents

• Methods

Methods

json.parse(text) #

json

Parses a JSON string into a JavaScript value. Throws if the text is not valid JSON.

PARAMETERS

text string

JSON source text to parse.

RETURNS: any The parsed JavaScript value — object, array, string, number, boolean, or null.

import { json } from "system";

const obj = json.parse('{"name":"Novadesk","version":1}');
console.log(obj.name);    // "Novadesk"
console.log(obj.version); // 1

json.stringify(value [, space]) #

json

Converts a JavaScript value to a JSON string.

PARAMETERS

value any

The JavaScript value to serialize.

space number | string OPTIONAL

Indentation for pretty-printing. Pass a number of spaces or a string.

RETURNS: string The JSON-encoded string representation of the value.

import { json } from "system";

const s = json.stringify({ name: "Novadesk", ok: true }, 2);
console.log(s);
// {
//   "name": "Novadesk",
//   "ok": true
// }

json.read(path) #

json

Reads a JSON file from disk and parses it. If the file exists but contains only whitespace, returns an empty object {}. Throws if the file exists but contains invalid JSON.

Path Resolution

Paths are resolved relative to the current script directory. If no current script directory is available, falls back to the entry script directory, and finally to the widgets directory.

PARAMETERS

path string

Absolute path or path relative to the entry script directory.

RETURNS: object | array | null

import { json } from "system";

const data = json.read(__dirname + "\\settings.json");
if (data !== null) {
  console.log("theme:", data.theme);
}

json.write(path, value [, merge]) #

json

Writes a value as pretty-printed JSON to a file (indented with 4 spaces). When merge is true, the existing file is read first and a JSON merge-patch is applied — useful for updating specific fields without overwriting others.

Path Resolution

Paths are resolved relative to the current script directory. If no current script directory is available, falls back to the entry script directory, and finally to the widgets directory.

JSON Merge Patch

When using merge: true, the function performs JSON Merge Patch (RFC 7396) to combine the existing file content with the new value. This allows selective updates of object properties.

PARAMETERS

path string

Absolute path or path relative to the entry script directory.

value any

The value to serialize and write.

merge boolean OPTIONAL

false (default) overwrites the file. true applies JSON merge-patch against the existing file.

RETURNS: boolean true on success, false on failure.

import { json } from "system";

// Overwrite
json.write(__dirname + "\\settings.json", { theme: "dark", refreshMs: 500 });

// Merge — only updates refreshMs, leaves other fields intact
json.write(__dirname + "\\settings.json", { refreshMs: 1000 }, true);