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)
      }
  }
  %%

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

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)

• 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.

# 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" 

• Ubuntu setup: if an error is reported by gradle similar to error while loading shared libraries: libtinfo.so.5, install libncurses-dev with apt install libncurses-dev. See also Kotlin/Native Setup instructions, and this similar issue in the Ktor project along with its fix, here

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/

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