KSON – When JSON and YAML Had a Baby

TL;DR

TL;DR: KSON is a config file format that combines JSON’s rigor with YAML’s readability — whitespace-insensitive, embeddable, and available for JS, Python, Rust, and the JVM.

Source and Accuracy Notes

⚠️ This section is MANDATORY. All links must be verified from actual source, not guessed.

• Project page: kson.org ← MUST visit and verify
• Source repository: github.com/kson-org/kson ← MUST read README
• License: Apache-2.0 (verified via LICENSE file on GitHub)
• Online playground: kson.org/playground

What Is KSON?

KSON (Kson Structured Object Notation) is a configuration file format pitched as a “verified superset of JSON” that also aims to be as readable as YAML. It was born out of frustration with whitespace sensitivity, poor error messages, and the lack of tooling in most config formats today.

The pitch: take everything developers like about JSON (strict types, no whitespace magic, easy to parse) and everything they like about YAML (human-readable, comments, clean syntax) — and leave the讨厌 parts behind.

From the official README:

“KSON combines the best aspects of JSON and YAML — robust and efficient like JSON, clean and readable like YAML.”

Key claims from the project:

• Whitespace is NOT significant — unlike YAML, indentation doesn’t change meaning
• Comments supported — single-line # comments, like in most programming languages
• Embed blocks — embed code in any language with %language ... %% syntax
• Verified superset of JSON — any valid JSON is valid KSON (PR #72)
• Native JSON Schema support — validation built in (PR #186)
• Transpiles to YAML — comments are preserved in the output (PR #80)

Supported Platforms

KSON implementations exist for:

• JavaScript/TypeScript — @kson_org/kson on npm
• Python — kson-lang on PyPI
• Rust — kson-rs on crates.io
• JVM — org.kson:kson-jvm on Maven Central
• Kotlin Multiplatform — org.kson:kson

Language bindings are also available for Rust and Python via separate library packages.

Editor Support

KSON has first-class IDE support:

• VS Code — KSON extension on the Visual Studio Marketplace
• JetBrains IDEs — KSON plugin on the JetBrains Marketplace
• LSP — Language Server Protocol implementation for any LSP-compatible editor

KSON Syntax at a Glance

Here’s a sample from the official README showing KSON’s syntax:

# Kson syntax note: whitespace is NOT significant!
person:
  name: 'Leonardo Bonacci'
  nickname: Fibonacci
  favorite_books:
    - title: Elements
      author: Euclid

    - title: Metaphysics
      author: Aristotle
      .
  favorite_numbers:
    - - 0
      - 1
      - 1
      - 2
      - '...'
      =
    - '(1 + √5)/2'
    - π
  # A Kson "embed block" containing Kotlin code
  favorite_function: %kotlin
    /**
     * Calculates the nth number in the Fibonacci sequence
     */
    fun fibonacci(n: Int): Long {
      if (n < 0) throw IllegalArgumentException("Input must be non-negative")
      return when (n) {
        0 -> 0
        1 -> 1
        else -> fibonacci(n - 1) + fibonacci(n - 2)
      }
    }
    %%

Key syntax markers:

• . — ends a list item explicitly (like YAML’s -)
• = — ends a map or object explicitly
• %kotlin ... %% — an embed block for Kotlin code with syntax highlighting
• ' or " — optional quotes around strings (whitespace-insensitive parsing)

Practical Evaluation Checklist

• Ease of adoption: Valid JSON is already valid KSON. Drop-in replacement for most configs.
• Toolability: LSP, VS Code, JetBrains — first-class IDE support from day one.
• Multi-language: Works wherever your stack lives: JS, Python, Rust, JVM.
• Escape hatches: Embed blocks let you stuff code directly in config — useful for function definitions, custom logic.
• Transpilation: Can round-trip to YAML with comments preserved — useful for migrating legacy YAML configs.

Security Notes

KSON itself is a data format. Embedded code blocks (%kotlin ... %%) are not executed by the KSON parser — they are stored as raw strings for tooling purposes (syntax highlighting, LSP analysis). Actual execution depends on whatever consumer reads the KSON file.

As with any config format: treat KSON files as untrusted input if they come from external sources, and validate against a JSON Schema if you need strict type enforcement (KSON has native JSON Schema support built in).

FAQ

Q: How is KSON different from JSON with comments? A: KSON is whitespace-insensitive where JSON-with-comments is not. In JSON, {"a": 1, "b": 2} and {"a":1,"b":2} are equivalent, but JSON doesn’t allow comments at all. KSON adds comments and readable formatting while remaining a strict superset of JSON.

Q: How is KSON different from YAML? A: The critical difference is whitespace sensitivity. In YAML, indentation is semantics — bad indent can silently change your config’s meaning. KSON ignores indentation for parsing purposes, so the format is robust against copy-paste and reformatting.

Q: Can I use KSON in production today? A: The core library for JVM/Kotlin is the most mature. JS and Python bindings are available but their maturity varies. Check each language package’s release history on its respective package registry before committing to a production deployment.

Q: Does KSON have a schema validation tool? A: Yes. KSON has native JSON Schema support (merged in PR #186). You can validate KSON documents against a JSON Schema without additional tooling.

Q: Where can I try it without installing anything? A: The online playground at kson.org/playground lets you write KSON and see it transpile to JSON or YAML in real time.

Conclusion

KSON is an interesting middle ground between JSON’s predictability and YAML’s ergonomics. Its strongest selling points are the whitespace insensitivity (the killer feature that eliminates an entire class of YAML foot-guns), multi-language support, and solid IDE integration.

If you’re currently using YAML for configuration and keep running into whitespace-related bugs, KSON is worth a look — especially since valid JSON config files are already valid KSON, making incremental migration straightforward.

Try the online playground or install the VS Code extension to get a feel for the syntax.