Combines JSON and YAML features for a robust, readable, and toolable data format. Offers flexible syntax, native JSON Schema support, and code embed functionality. Supports multiple platforms and IDE environments.
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:
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.
# 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"
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'
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
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.
Clone this repo, then run ./gradlew check in its root dir to validate everything builds and runs correctly.
buildSrc/ project, which is built and tested as a prerequisite for this buildIntelliJ setup:
build.gradle.kts file directly and select "Open as Project" when promptedBuild, Execution, Deployment -> Build Tools -> Gradle, for Gradle JVM:
Contents/Home folder of the JDK under gradle/jdk (this JDK is installed the first time you run ./gradlew check from the command line)Surfaced from shared tags and platforms — no rankings paid for.