KSON: Kson Structured Object Notation

KSON combines the best aspects of JSON and YAML—robust and efficient like JSON, clean and readable like YAML. KSON is designed to be toolable and has a flexible syntax that is usually auto-formatted to look like this:

# 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 using recursion
     */
    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)
      }
  }
  %%

Why KSON?

One of the key things KSON wants to say is: let's keep everything that's great about YAML and JSON as "Configuration User Interfaces", and let's make those interfaces more toolable, reliable, and fun. Here are some of the ways we do that:

• KSON is a verified superset of JSON, has native JSON Schema support, transpiles reliably to YAML (with comments preserved!), and is likely available wherever you want it—current supported platforms: JS, Python, Rust, JVM, and Kotlin Multiplatform

• KSON is also widely available in developer tools, with support for VS Code, Jetbrains IDEs, and anywhere you can plug in an LSP.

Learn more at kson.org, try it out now in our online playground, and come join our community on Zulip

Developer setup

We welcome you to dive in this project to explore, experiment, or contribute. A lot of care, craft, attention and joy went into making this project understandable and approachable. Hopefully some of that shines through when you dive in. Please feel free to ask questions on Zulip if you want any support finding your way around the code here.

• Clone this repo, then run ./gradlew check in its root dir to validate everything builds and runs correctly.

  • There should be no other dependencies needed (even the JDK is defined and managed by the build). See Troubleshooting setup below if you run into any issues
  • Note that the build depends on the embedded buildSrc/ project, which is built and tested as a prerequisite for this build

• IntelliJ setup:

  • Ensure you have the Kotlin and Gradle plugins installed
  • Open the root build.gradle.kts file directly and select "Open as Project" when prompted
  • In Settings, under Build, Execution, Deployment -> Build Tools -> Gradle, for Gradle JVM:
    • choose "Add JDK..." and select the Contents/Home folder of the JDK under gradle/jdk (this JDK is installed the first time you run ./gradlew check from the command line)

Project structure

• The root build of this project contains the core Kson implementation
  • kson-lib/ defines the public interface for the Kson project. This should be the only module that depends on the root build
  • lib-python/ defines an idiomatic Python interface on kson-lib/
  • lib-rust/ defines an idiomatic Rust interface on kson-lib/
  • tooling/ contains tooling/editor/IDE support for Kson
• The buildSrc/ project implements non-trivial custom build components needed by this project. It is developed as a separate, independent project. See the buildSrc readme for details.

Some useful gradle commands:

# build and test
./gradlew build

# run all tests
./gradlew allTests

# build (if necessary) and run jvm tests
./gradlew jvmTest
./gradlew jvmTest --tests "org.kson.parser.*" 

# Run a test and rerun each time a source file changes.
./gradlew jvmTest --continuous --tests "org.kson.parser.LexerTest" 

Static analysis (detekt)

Detekt runs on every Kotlin module. Rule config lives in detekt.kson, which is transpiled to detekt.yml at build time (the .yml is gitignored — edit the .kson instead).

Each module carries a detekt-baseline.xml file listing grandfathered findings from before detekt was introduced. Detekt ignores these existing issues but still fails the build on anything new, so new code is held to the current rules while pre-existing debt can be paid down incrementally.

To refresh the baselines after paying down debt (or after tightening rules):

# 1. Must be green first — proves no NEW findings are hiding
./gradlew detekt

# 2. Regenerate the baseline snapshots against current findings
./gradlew detektBaseline

# 3. Diff should only show <ID> lines being removed. If anything is added,
#    step 1 didn't really pass.
git diff '**/detekt-baseline.xml'

Releases

• See the Tags page for the list of released KSON versions.
• See the Release Process Documentation for details on performing releases.

Troubleshooting setup:

Kson Editors and Tooling

KSON can be used in VS Code or IntelliJ with a simple gradle command.

To run either IDE you can run the following gradlew task from the root directory:

./gradlew :tooling:lsp-clients:npm_run_vscode # starts VS Code IDE
./gradlew runIde # starts IntelliJ IDE 

For more information on our tooling see tooling/

Notes

Many thanks to @munificent for making all of this more accessible by writing the wonderful Crafting Interpeters — Part I and Part II in particular are strongly recommended reading for anyone exploring this code