kOS-simpleJson

Overview

This addon extends kOS with simple JSON functionality, allowing you to serialize kOS data structures to basic JSON strings and parse plain JSON strings back into kOS structures. It uses the SimpleJson library internally for efficient JSON processing. It also exposes helper suffixes to validate JSON strings and return safe fallbacks when parsing fails, so scripts stay running.

While kOS provides its own READJSON and WRITEJSON functions which allow complete serialization and deserialization without loss of types, this addon provides the functionality to read and write plain JSON data without the need for custom types. The only drawback is that when converting a structure to and from JSON, it might not be the same type anymore. See the section about supported type conversions for more info.

Features

• JSON Stringification: Convert kOS structures (Lexicons, Lists, primitives, etc.) to JSON strings
• JSON Parsing: Parse JSON strings into kOS structures
• Safe Parsing Helpers: Validate JSON and supply fallbacks via PARSEORELSE, PARSEORELSEGET, and ISPARSEABLE
• Type Support: Handles strings, numbers (int/double), booleans, arrays, and objects
• Robust Number Handling: Automatically handles numeric type conversions and ranges
• Special Structure Support: Serializes PID loops and ranges correctly

Requirements

• kOS

Installation

Use CKAN or install it manually:

1. Download the latest release
2. Extract the contents into your KSP root folder
3. The addon will be loaded automatically when KSP starts

Your directory structure should look like:

KSP_ROOT/
└─ GameData/
   └─ kOS-simpleJson/
      ├─ kOS-simpleJson.dll
      ├─ kOS-simpleJson.version
      ├─ LICENSE
      └─ README

Usage

The addon provides several functions accessible through the base path ADDONS:JSON:

STRINGIFY

Converts a kOS structure to a JSON string. Works with kOS-serializable structures (Lexicons, Lists, primitives, PID loops, ranges). Keys of object-like structures must be strings.

// Stringify a lexicon
SET myLex TO LEXICON("name", "Rocket", "altitude", 1000, "active", True).
SET jsonString TO ADDONS:JSON:STRINGIFY(myLex).
PRINT jsonString.
// Output: {"name":"Rocket","altitude":1000,"active":true}

// Stringify a list
SET myList TO LIST(1, 2, 3, "four").
SET jsonString TO ADDONS:JSON:STRINGIFY(myList).
PRINT jsonString.
// Output: [1,2,3,"four"]

// Stringify primitives
PRINT ADDONS:JSON:STRINGIFY(42).        // Output: 42
PRINT ADDONS:JSON:STRINGIFY("hello").   // Output: "hello"
PRINT ADDONS:JSON:STRINGIFY(True).      // Output: true

ISSTRINGIFIABLE

Checks if a structure can be serialized to JSON without throwing.

SET myLex TO LEXICON(0, "<-- invalid key", "name", "Rocket", "altitude", 1000).
IF ADDONS:JSON:ISSTRINGIFIABLE(myLex) {
    SET jsonString TO ADDONS:JSON:STRINGIFY(myLex).
    PRINT jsonString.
} ELSE {
    PRINT "Structure cannot be serialized".
}

PARSE

Parses a JSON string into a kOS structure. Throws if the JSON is invalid.

// Parse JSON object
SET jsonString TO "{""name"":""Rocket"",""altitude"":1000}".
SET myLex TO ADDONS:JSON:PARSE(jsonString).
PRINT myLex["name"].      // Output: Rocket
PRINT myLex["altitude"].  // Output: 1000

// Parse JSON array
SET jsonString TO "[1,2,3,4,5]".
SET myList TO ADDONS:JSON:PARSE(jsonString).
PRINT myList[0].  // Output: 1

// Parse primitives
PRINT ADDONS:JSON:PARSE("42").      // Output: 42
PRINT ADDONS:JSON:PARSE("true").    // Output: True

PARSEORELSE

Parses a JSON string, or returns the provided fallback if parsing fails.

SET badJson TO "{""name"":""Rocket""".
SET fallback TO LEXICON("name", "Fallback", "active", False).
SET data TO ADDONS:JSON:PARSEORELSE(badJson, fallback).
PRINT data["name"].    // Output: Fallback

PARSEORELSEGET

Parses a JSON string, or calls a delegate to produce a fallback when parsing fails. The delegate function is only called if parsing the given JSON fails.

DECLARE FUNCTION BuildDefault {
    RETURN LEXICON("status", "unknown", "tries", 1).
}.
SET maybeJson TO "}not-json{".
SET data TO ADDONS:JSON:PARSEORELSEGET(maybeJson, BuildDefault@).
PRINT data["status"].   // Output: unknown

ISPARSEABLE

Checks if a string can be parsed as JSON without throwing in kOS.

SET candidate TO "{""value"":1}".
IF ADDONS:JSON:ISPARSEABLE(candidate) {
    PRINT ADDONS:JSON:PARSE(candidate).
} ELSE {
    PRINT "Invalid JSON".
}

Supported Types

kOS to JSON (STRINGIFY)

JSON to kOS (PARSE)

Examples

Working with API Responses

// Simulating an API response
SET apiResponse TO "{""vessel"":{""name"":""Explorer 1"",""mass"":5000,""parts"":25}}".
SET data TO ADDONS:JSON:PARSE(apiResponse).
PRINT "Vessel: " + data["vessel"]["name"].
PRINT "Mass: " + data["vessel"]["mass"].

Saving Configuration

// Create configuration
SET config TO LEXICON(
    "launchAzimuth", 90,
    "targetAltitude", 80000,
    "stages", LIST(
        LEXICON("fuel", 100, "engines", 1),
        LEXICON("fuel", 200, "engines", 2)
    )
).

// Save to file
SET jsonConfig TO ADDONS:JSON:STRINGIFY(config).
LOG jsonConfig TO "0:/config.json".

// Load from file
SET loadedJson TO OPEN("0:/config.json"):READALL:STRING.
SET loadedConfig TO ADDONS:JSON:PARSE(loadedJson).

Technical Details

The addon implements the IFormatWriter interface from kOS.Safe.Serialization, using the SimpleJsonFormatter class to handle serialization. Deserialization is handled by the JsonDeserializer, skipping the conversion to dumps. The main entry point is the SimpleJsonAddon class, which is decorated with the [kOSAddon("JSON")] attribute to register it with kOS.

Known Limitations

• Circular references are not supported and will cause serialization errors
• Some complex kOS types may not serialize correctly (please report as issues)
• JSON null values are converted to empty strings

Credits

• Built using KSPBuildTools
• Uses kOS built-in SimpleJson for JSON processing
• Built for kOS (Kerbal Operating System)
• Copyright © Throin 2025