Skip to content

Getting Started

KSON is a fully self-contained configuration language designed to be an improved interface on plain text data. This guide will help you get started with KSON across different environments and use cases.

Playground

Try KSON directly in your browser without any installation: kson.org/playground

Languages

Python

Install via pip:

pip install kson-lang

Requires Python 3.11+. Wheels are published for Linux x86_64 (glibc 2.34+), macOS arm64, and Windows x86_64.

Usage:

from kson import Kson, TranspileOptions, Result

result = Kson.to_json("key: [1, 2, 3, 4]", TranspileOptions.Json(retain_embed_tags=True))
assert isinstance(result, Result.Success)
print(result.output())

Rust

Add to your Cargo.toml:

[dependencies]
kson-rs = "0.3.0"

Usage:

use kson_rs::{transpile_options, Kson};

fn main() {
    let json = Kson::to_json("key: [1, 2, 3, 4]", transpile_options::Json::new(true))
        .map_err(|_| "unreachable: kson input is guaranteed to be valid!")
        .unwrap();
    println!("{}", json.output());
}

kson-rs links a native library, which cargo downloads for your platform automatically. See the crate readme for supplying your own binaries.

Java/JVM

For JVM-only projects, add to your build.gradle:

dependencies {
    implementation("org.kson:kson-jvm:0.3.0")
}

Or with Maven in pom.xml:

<dependency>
    <groupId>org.kson</groupId>
    <artifactId>kson-jvm</artifactId>
    <version>0.3.0</version>
</dependency>

Usage:

import org.kson.Kson;
import org.kson.Result;
import org.kson.TranspileOptions;

public class Main {
    public static void main(String[] args) {
        // Convert KSON to JSON
        Result result = Kson.INSTANCE.toJson(
            "server:\n" +
            "  host: localhost\n" +
            "  port: 8080",
            new TranspileOptions.Json()
        );

        if (result instanceof Result.Success) {
            System.out.println(((Result.Success) result).getOutput());
        } else if (result instanceof Result.Failure) {
            ((Result.Failure) result).getErrors().forEach(System.out::println);
        }
    }
}

Kotlin Multiplatform (JVM, JS, Native)

For Kotlin Multiplatform projects, add to your build.gradle:

dependencies {
    implementation("org.kson:kson:0.3.0")
}

Usage:

import org.kson.Kson
import org.kson.Result

fun main() {
    // Convert KSON to JSON
    val result = Kson.toJson(
        """
            server: {
                host: "localhost"
                port: 8080
            }
        """.trimIndent()
    )
    when (result) {
        is Result.Success -> {
            println(result.output)
        }
        is Result.Failure -> {
            println(
                result.errors.joinToString("\n")
            )
        }
    }
}

JavaScript/TypeScript

Install via npm:

npm i @kson_org/kson

Usage:

import { Kson, Result } from '@kson_org/kson';

const kson = Kson.getInstance();

// Convert KSON to JSON
const result = kson.toJson('key: [1, 2, 3, 4]');
if (result instanceof Result.Success) {
  console.log(result.output);
}

Editor Support

IntelliJ IDEA

Install the KSON plugin directly from the JetBrains Marketplace:

  1. Open IntelliJ IDEA
  2. Go to Settings/Preferences → Plugins
  3. Search for "KSON"
  4. Click Install and restart the IDE

Visual Studio Code

Install the KSON extension from the VS Code Marketplace:

  1. Open VS Code
  2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
  3. Search for "KSON"
  4. Click Install

The extension is also available on Open VSX for editors that use it, and directly from the VS Code Marketplace.

CLI Tool

The KSON CLI provides command-line utilities for working with KSON files.

Installation

The CLI is not published to any package manager yet. However, it is possible to use it by cloning the source code and following the instructions.

git clone github.com/kson-org/kson
cd kson
./gradlew :tooling:cli:buildNativeImage

This will generate the cli-binary in tooling/cli/build/native/nativeCompile/.

Development/Building from Source

If you want to build KSON from source:

# Clone the repository
git clone https://github.com/kson-org/kson.git
cd kson

# Build with Gradle
./gradlew check

Next Steps

  • Read the Syntax Guide to learn KSON's syntax
  • Join our Zulip community for help and discussions